---
title: "settings.json reference"
description: "Field-by-field reference for .trevize/settings.json — every key, its type, whether it's required, and what it does."
---

> 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.

# settings.json reference

A complete reference for [`.trevize/settings.json`](/configuration/settings-json).
For explanations and examples, see the [Configuration](/configuration) guides.

## Top-level

| Field         | Type     | Required | Description                                                                 |
| ------------- | -------- | -------- | --------------------------------------------------------------------------- |
| `$schema`     | string   | no       | JSON schema URL, for editor autocomplete and validation.                    |
| `workspaceId` | string   | no       | The Trevize workspace this project belongs to (used by the [MCP](/integrations/mcp) server). |
| `projectId`   | string   | no       | The `org/repo` identifier. Can be auto-detected from the git remote.        |
| `hooks`       | object   | no       | Lifecycle hook commands. See [`hooks`](#hooks).                             |
| `preview`     | object   | no       | Preview targets and processes. See [`preview`](#preview).                   |
| `resources`   | object   | no       | Managed resource declarations. See [`resources`](#resources).               |

The file is read from `.trevize/settings.json` (canonical) or the legacy
`.tervezo/settings.json` (deprecated fallback).

## `hooks`

Commands run at sandbox lifecycle points. See [Hooks](/configuration/hooks).

| Field                | Type                    | Required | Description                                             |
| -------------------- | ----------------------- | -------- | ------------------------------------------------------- |
| `hooks.SandboxReady` | array of `{ command }`  | no       | Commands run **in order** once the sandbox is ready.    |
| `…[].command`        | string                  | yes      | The shell command to run.                               |

`SandboxReady` is currently the only supported hook event.

## `preview`

Declares how to serve your app. See [Preview](/configuration/preview).

| Field                   | Type                    | Required | Description                                             |
| ----------------------- | ----------------------- | -------- | ------------------------------------------------------- |
| `preview.targets`       | map of name → target    | yes      | Named preview targets.                                  |
| `preview.defaultTarget` | string                  | no       | Target to launch by default. Must exist in `targets`.   |

### Target

A target uses **either** a `processes` array **or** the single-process
`command` + `port` shorthand.

| Field            | Type                    | Required    | Description                                                    |
| ---------------- | ----------------------- | ----------- | ------------------------------------------------------------- |
| `processes`      | array of process        | conditional | Processes for a multi-process target.                          |
| `defaultProcess` | string                  | no          | Process shown by default. Must match a process `name`.         |
| `command`        | string                  | conditional | Shorthand: command for a single-process target.                |
| `port`           | number                  | conditional | Shorthand: port for a single-process target (1–65535).         |
| `cwd`            | string                  | no          | Working directory shared by all processes in the target.       |
| `env`            | map of string → string  | no          | Literal env vars shared by all processes.                      |
| `secretEnv`      | map of string → string  | no          | Secret env vars (var → workspace secret key) for all processes. |

### Process

| Field       | Type                    | Required | Description                                             |
| ----------- | ----------------------- | -------- | ------------------------------------------------------- |
| `name`      | string                  | yes      | Unique name within the target (e.g. `web`, `api`).      |
| `command`   | string                  | yes      | Shell command to start the process.                     |
| `port`      | number                  | yes      | Port the process listens on (1–65535).                  |
| `cwd`       | string                  | no       | Working directory, relative to the sandbox home.        |
| `env`       | map of string → string  | no       | Literal env vars (merged on top of the target's `env`). |
| `secretEnv` | map of string → string  | no       | Secret env vars, resolved from workspace secrets.       |

### Interpolation variables

`env` values may reference `${VAR}`:

| Variable                   | Description                                             |
| -------------------------- | ------------------------------------------------------- |
| `${PREVIEW_URL}`           | The preview's base URL.                                 |
| `${PREVIEW_HOST}`          | The preview's host.                                     |
| `${PREVIEW_URL_<PROCESS>}` | A specific process's URL (uppercase process name).      |
| `${PREVIEW_HOST_<PROCESS>}`| A specific process's host.                              |
| resource variables         | e.g. `${NEON_DATABASE_URL}` — see [`resources`](#resources). |

## `resources`

Declares managed resources to provision per run. See
[Resources](/configuration/resources).

| Field                   | Type                    | Required | Description                                                       |
| ----------------------- | ----------------------- | -------- | ---------------------------------------------------------------- |
| `resources.<id>`        | object                  | no       | Keyed by integration id (`neon`, `supabase`).                    |
| `resources.<id>.env`    | map of string → string  | no       | Maps `<your app's variable>` → `<the variable Trevize provides>`. |

### Provided variables

| Resource   | Injected variables                                                  |
| ---------- | ------------------------------------------------------------------- |
| `neon`     | `NEON_DATABASE_URL`, `NEON_BRANCH_ID`                                |
| `supabase` | `SUPABASE_DATABASE_URL`, `SUPABASE_BRANCH_ID`, `SUPABASE_BRANCH_REF` |

Source: https://docs.trevize.dev/reference/settings-reference/index.mdx