Preview targets & processes

The preview block declares how to run your application inside a sandbox so reviewers get a live preview during a session or on an implementation. You define one or more targets, each made up of one or more processes.

Targets

preview.targets is a map of named targets. An optional defaultTarget picks which one launches when none is specified.

{
  "preview": {
    "defaultTarget": "dev",
    "targets": {
      "dev": {
        "defaultProcess": "web",
        "processes": [
          { "name": "web", "command": "bun run dev", "port": 5173 }
        ]
      }
    }
  }
}

Processes

Each process runs a command and exposes a port the gateway proxies to. A process has:

For a multi-process target, set defaultProcess to the process shown by default (it must match one of the process names).

Single-process shorthand

If a target runs just one process, you can set command and port directly on the target instead of a processes array:

{
  "preview": {
    "targets": {
      "docs": { "command": "bun run dev", "port": 4321 }
    }
  }
}

A target must have either a processes array or both command and port.

Environment variables

• env — literal KEY: "value" pairs. Can be set at the target level (shared by all processes) or per process (merged on top).
• secretEnv — maps an environment variable to a workspace secret key, resolved at runtime so secrets never live in your repo.

Interpolation

Values may reference runtime variables with ${VAR}:

• ${PREVIEW_URL} / ${PREVIEW_HOST} — the preview’s URL and host.
• ${PREVIEW_URL_<PROCESS>} / ${PREVIEW_HOST_<PROCESS>} — a specific process’s URL/host, so one process can point at another (e.g. a frontend at its API).
• Resource variables such as ${NEON_DATABASE_URL} — see Resources.

{
  "preview": {
    "targets": {
      "dev": {
        "defaultProcess": "web",
        "processes": [
          {
            "name": "web",
            "command": "bun run dev",
            "port": 5173,
            "env": { "VITE_API_URL": "${PREVIEW_URL_API}" }
          },
          { "name": "api", "command": "bun run api", "port": 8787 }
        ]
      }
    }
  }
}