Deployment

Three Vercel projects deploy from the same monorepo. Each has its own Root Directory and env-var scope, but all three pull from the same Git history.

Vercel project map#

Each Vercel project must set its own env vars — Vercel does not share them across projects in the same org. For the public site this means CLERK_*, WORDPRESS_*, MONGODB_*, MUX_*, SALESFORCE_* etc. For workspace it means the same vars (it consumes the same backends). For webdocs it means almost nothing — just NEXT_PUBLIC_* flags if any.

DNS#

After adding each subdomain in Vercel, copy the assigned CNAME target Vercel gives you and paste it into the DNS provider. Vercel issues SSL certificates automatically once DNS resolves.

Cutover sequence (workspace)#

1. Create the matters-workspace Vercel project pointing at this repo, Root Directory apps/workspace. Don't add the domain yet.
2. Populate env vars (CLERK_PUBLISHABLE_KEY, CLERK_SECRET_KEY, CLERK_WEBHOOK_SECRET, MONGODB_CONNECTION_STRING, WORDPRESS_URL, WORDPRESS_HOSTNAME, WORDPRESS_WEBHOOK_SECRET, SLACK_DEMO_WEBHOOK_URL, MUX_*, SALESFORCE_*, MAILERLITE_*, SENTRY_*).
3. Trigger a build. Verify it builds clean and the _not-found prerender succeeds.
4. Verify the preview deploy: log in, navigate to a workspace module, exercise an RBAC-gated mutation, hit the Clerk webhook with a test event.
5. Set Clerk cookie domain to .matters.ai in the Clerk dashboard. This enables SSO across matters.ai ↔ workspace.matters.ai.
6. Add the domain workspace.matters.ai to the Vercel project. Wait for SSL.
7. Smoke test on the real subdomain.
8. Flip the redirect on the public site: set WORKSPACE_SUBDOMAIN_URL=https://workspace.matters.ai on the matters-web Vercel project. This activates the gated /workspace/* and /auth/* permanent redirects defined in root next.config.ts.

Rollback#

Each Vercel project keeps the last ~20 deployments. To roll back:

Vercel dashboard → matters-workspace → Deployments → click the prior deploy → "Promote to Production"

If the rollback target is older than 20 deploys, redeploy the relevant Git SHA from the Deployments → New Deployment flow.

Common build issues#

• ENOSPC during webpack build — disk full on the build machine. Clear .next/ and labs/.next/ (the labs sibling app is large). Locally: rm -rf .next labs/.next apps/workspace/.next.
• Tailwind class not found (border-border etc.) — apps/workspace needs apps/workspace/tailwind.config.ts re-exporting the root config. Already in place; check it's not deleted.
• Sentry instrumentation pulled from repo root into apps/workspace build — apps/workspace ships a instrumentation.ts stub to short-circuit auto-detection. Don't delete it.
• Clerk "invalid publishable key" at prerender — happens with dummy keys (pk_test_dummy). Real keys build clean. Configure Vercel env vars before triggering a build.

CI#

Pre-commit hooks (Husky) run pnpm run type:check. CI runs via .github/workflows/ci.yml (type-check + lint + build) on every PR and on push to main / monorepo, but it does not hard-gate merges today — lint is continue-on-error, so merging without fully green CI is still allowed. Turning CI into a required status check is on the PROD_CHECKLIST.