# toupas.json

Lives in the app's folder and is committed with the code. `toupas_make_live` writes it the first time from what it detects; edit it only to change something. It says **how** to prepare and run the app, not which Toupas app it is (that's `.toupas/project.json`, which stays out of git).

```json
{
  "$schema": "https://toupas.com/schema/v1/toupas.json",
  "type": "server",
  "runtime": "node24",
  "framework": "express",
  "build": { "install": "npm ci", "command": "npm run build" },
  "start": "node server.js",
  "healthCheck": { "path": "/health" },
  "memoryMb": 256
}
```

```json
{ "type": "static", "framework": "vite", "build": { "command": "npm run build", "output": "dist" }, "static": { "spa": true } }
```

| Field | For | Notes |
|---|---|---|
| `type` | all | `static` or `server` (required) |
| `runtime` | server | `node24`, `node22`, `python313` or `python312` (`toupas_list_runtimes`). Without it: `node22` / `python312` when `engines.node`, `.nvmrc`, `.node-version`, `.python-version` or `requires-python` ask for exactly that version, else the newest |
| `framework` | all | A preset that fills in the rest (toupas://docs/frameworks) |
| `build.install` | server | Runs in the builder; default from the lockfile |
| `build.command` | all | Runs in the builder (server) or on this computer (static) |
| `build.output` | static | The folder that goes live, e.g. `dist` |
| `start` | server | Run as `/bin/sh -c "exec <start>"`, so `$PORT` works |
| `healthCheck.path` / `healthCheck.timeoutSeconds` | server | Default `/` and 60 (at most 300) |
| `memoryMb` | server | Multiple of 64, 128–2048; default 128. Counts toward the account's RAM |
| `include` / `exclude` | all | Extra glob patterns. `.env`, `.env.*`, `*.pem`, `*.key`, `.git`, `node_modules` and `.venv` are always left out |
| `static.spa` | static | Serve `index.html` for unknown paths |
| `static.cleanUrls` | static | `/about` serves `/about.html` (default true) |
| `systemPackages` | server | Debian 13 packages the app needs when it runs, e.g. `["ffmpeg", "poppler-utils"]` (at most 30, names from https://packages.debian.org). The first time, Toupas builds them into the runtime's images (a few minutes); after that it's instant |
| `buildPackages` | server | Debian packages only the build needs, e.g. `["libvips-dev"]` |

Unknown fields are refused, so typos fail loudly. Use `systemPackages` only for software npm or pip can't install (ffmpeg, Chromium for Puppeteer, poppler, ImageMagick).