---
title: "Preview targets & processes"
description: "Declare the processes that serve your app so reviewers get a live preview — command, port, env, and defaults."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.trevize.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Preview targets & processes

The **`preview`** block declares how to run your application inside a sandbox so
reviewers get a **live preview** during a [session](/concepts/sessions) or on an
[implementation](/concepts/tasks). 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.

```json
{
  "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:

| Field       | Required | Description                                               |
| ----------- | -------- | --------------------------------------------------------- |
| `name`      | yes      | Unique name within the target (e.g. `web`, `api`).        |
| `command`   | yes      | Shell command to start the process.                       |
| `port`      | yes      | Port the process listens on (1–65535).                    |
| `cwd`       | no       | Working directory, relative to the sandbox home.          |
| `env`       | no       | Literal environment variables for this process.           |
| `secretEnv` | no       | Environment variables resolved from **workspace secrets**. |

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

### 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:

```json
{
  "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](/configuration/resources).

```json
{
  "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 }
    ]
  }
}
  }
}
```

> **Validation**
>
> `defaultTarget` must name a real target, and `defaultProcess` must name a real
> process within its target — otherwise the preview config is rejected.

Source: https://docs.trevize.dev/configuration/preview/index.mdx