Deployment Checklist

This checklist covers deploying the docs site itself (this site) as well as verifying that features requiring the live app — like the interactive API reference — work correctly after deployment.

Prerequisites

• vercel CLI installed: npm install -g vercel
• Logged in: vercel whoami (run vercel login if not)
• The main TheTerms app is deployed to app.theterms.app

Deploy the Docs Site

1. Build locally to catch errors first

   npm run build

   Expected: all pages build without errors.

2. Link to Vercel project (first time only)

   vercel link

   Select the existing theterms-docs project or create a new one.

3. Deploy to production

   vercel --prod

   The CLI prints a production URL on success (e.g., https://docs.theterms.app).

4. Verify the deployment

   Open the production URL and check:

   • Homepage loads
   • Sidebar navigation works
   • Search (Pagefind) returns results
   • Dark/light mode toggle works

Verifying the Interactive API Reference

The API Reference page embeds the Scalar UI, which fetches the OpenAPI spec directly from the browser. It requires:

1. The main app to be deployed and accessible at https://app.theterms.app
2. The app’s /api/v1/openapi.json endpoint to return CORS headers that allow https://docs.theterms.app

Troubleshooting: “Document could not be loaded”

If the Scalar viewer shows “Document ‘api-1’ could not be loaded”:

Cause: The browser’s fetch() for https://app.theterms.app/api/v1/openapi.json is being blocked. This is most commonly a CORS issue — the app needs to include Access-Control-Allow-Origin: https://docs.theterms.app (or *) on the OpenAPI spec endpoint.

Diagnosis steps:

1. Open browser DevTools → Network tab
2. Reload the /api-reference/reference/ page
3. Find the request to openapi.json
4. Check for a CORS error in the response headers or console

Fix in the main app:

Ensure the Hono app includes a CORS middleware on /api/v1/openapi.json. In apps/web/src/server/api/v1/index.ts, the cors() middleware should include the docs domain:

app.use('/openapi.json', cors({ origin: 'https://docs.theterms.app' }))

Or for development, use origin: '*' temporarily.

Local testing:

To test the Scalar viewer locally against a local app instance:

1. Run the main app: pnpm dev (in the theterms repo)
2. Run the docs: npm run dev (in this repo)
3. Temporarily update reference.mdx’s data-url to http://localhost:3000/api/v1/openapi.json
4. Revert before committing

Note

The Scalar data-proxy-url attribute proxies API call requests made from the interactive UI — not the initial spec fetch. The spec URL must be directly accessible from the browser.