Deploy to Netlify

Architecture overview

Component	Netlify product	Notes
Site (`apps/site`)	Netlify Sites	Next.js via `@netlify/plugin-nextjs`
the editor (`apps/editor`)	Netlify Sites	Static Vite build
Orchestrator (`apps/orchestrator`)	External host	Long-running Fastify server — deploy on Render, Fly, Railway, or any container host

The orchestrator is a long-running stateful server and cannot run as a Netlify Function. Deploy it on a platform that supports persistent processes.

Phase 1: Public site only (recommended start)

Deploy apps/site as a standalone Next.js site serving published content.

Netlify project setup

Connect your repository to Netlify
Configure build settings:
- Base directory: apps/site
- Build command: cd ../.. && pnpm install --frozen-lockfile && pnpm --filter @ai-site-editor/site build
- Publish directory: apps/site/.next
Install the Next.js plugin: add @netlify/plugin-nextjs via the Netlify UI or netlify.toml

netlify.toml (in repo root)

[build]
  base = "apps/site"
  command = "cd ../.. && pnpm install --frozen-lockfile && pnpm --filter @ai-site-editor/site build"
  publish = ".next"

[[plugins]]
  package = "@netlify/plugin-nextjs"

Environment variables (Phase 1)

Variable	Value	Required
`NODE_VERSION`	`22`	Yes
`ORCHESTRATOR_URL`	(leave unset)	No

In Phase 1, the site renders from published content only — no orchestrator needed.

Phase 2: Full editing stack

Deploy the editor

Create a separate Netlify site for apps/editor:

Base directory: apps/editor
Build command: cd ../.. && pnpm install --frozen-lockfile && pnpm --filter @ai-site-editor/editor build
Publish directory: apps/editor/dist

Editor environment variables

Variable	Value
`VITE_SITE_ORIGIN`	`https://<your-site>.netlify.app` (no trailing slash)
`VITE_ORCHESTRATOR_URL`	`https://<your-orchestrator-host>`
`VITE_SITE_DRAFT_SECRET`	Shared secret (must match site’s `DRAFT_MODE_SECRET`)

Deploy the orchestrator (external host)

The orchestrator requires a long-running process. Deploy on Render, Fly.io, Railway, or any container platform. See the Vercel deployment guide for Render-specific instructions.

Site environment variables (Phase 2)

Variable	Value
`ORCHESTRATOR_URL`	`https://<your-orchestrator-host>`
`SITE_PUBLISH_SITE_ID`	your site id — required whenever `ORCHESTRATOR_URL` is set
`SITE_PUBLISH_SESSION`	publish session name (optional, defaults to `dev`)
`NEXT_PUBLIC_ENABLE_EDITOR`	`1`
`NEXT_PUBLIC_EDITOR_ORIGIN`	`https://<your-editor>.netlify.app` (no trailing slash)
`DRAFT_MODE_SECRET`	Shared secret (must match the editor’s `VITE_SITE_DRAFT_SECRET`)
`PUBLISH_TOKEN`	The publish secret, passed to `createEditorApiHandler` as `publishSecret`. Set the same value on the orchestrator, which sends it as `x-publish-token`

PUBLISH_TOKEN is what makes publishing work at all here: the site’s POST /api/editor/publish refuses every request with a 401 under NODE_ENV=production when no secret is configured, and a production build is what Netlify serves. The same deploy also has a read-only filesystem, so a publish handler that rewrites a JSON file in the repository succeeds locally and fails here — publish to a CMS, a database, or a commit that triggers a rebuild.

Other platforms

Deployment guides for the following platforms are planned:

AWS Amplify — Next.js hosting + Lambda for orchestrator
Google Cloud Run — Container-based deployment for all three services
Docker Compose — Self-hosted deployment on any server

The orchestrator half of each of those is already covered by Docker deployment — it runs as a container anywhere that supports a long-lived process with a persistent volume. If one of these platforms is what you need documented next, get in touch.

Troubleshooting

See the production troubleshooting section — the same postMessage, CORS, and draft mode issues apply regardless of hosting platform.

Deploy

Run it safely

Watch it

Architecture overview

Phase 1: Public site only (recommended start)

Netlify project setup

netlify.toml (in repo root)

Environment variables (Phase 1)

Phase 2: Full editing stack

Deploy the editor

Editor environment variables

Deploy the orchestrator (external host)

Site environment variables (Phase 2)

Other platforms

Troubleshooting

​Architecture overview

​Phase 1: Public site only (recommended start)

​Netlify project setup

​netlify.toml (in repo root)

​Environment variables (Phase 1)

​Phase 2: Full editing stack

​Deploy the editor

​Editor environment variables

​Deploy the orchestrator (external host)

​Site environment variables (Phase 2)

​Other platforms

​Troubleshooting

Architecture overview

Phase 1: Public site only (recommended start)

Netlify project setup

netlify.toml (in repo root)

Environment variables (Phase 1)

Phase 2: Full editing stack

Deploy the editor

Editor environment variables

Deploy the orchestrator (external host)

Site environment variables (Phase 2)

Other platforms

Troubleshooting