runlot.json
The configuration file placed in the project directory. It records the name, entry point, asset directory and the services you have attached.
web/apps/cli/src/config.ts and internal/bundle/bundle.go. The content is generated from those sources when the documentation is built.{
"name": "my-app",
"org": "me",
"main": "src/index.ts",
"assets": "public",
"database": true
}Field
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | The project name. Used as the first label of the deployment URL. |
org | string | No | The organization slug. The --org option takes precedence over this setting. |
main | string | No | The worker entry point. If it is not set, only static assets are deployed. |
assets | string | No | The static asset directory. |
notFound | `"404" | "spa"` | No |
compatibilityDate | string | No | The workerd compatibility date. The format is YYYY-MM-DD. |
database | boolean | No | Declares that the project uses a database. runlot deploy reads it and creates one if missing. |
storage | boolean | No | Declares that the project uses file storage. runlot deploy reads it and creates it if missing. |
email | boolean | No | Declares email sending and receiving (docs/email.md) |
auth | boolean | No | Declares that the project uses application user auth. runlot deploy reads it and turns it on if missing, creating the database as well. |
framework | "next" | No | The framework adapter. The only value supported at present is next. |
triggers | { crons: string[] } | No | Scheduled execution. Put five-field cron expressions in crons, in UTC. See Scheduled execution. |
name is required. At least one of main and assets must be set; with neither there is no worker or static asset to serve. Projects that set framework are the exception — the build generates the entry point and the assets.
Fields that declare services
database, storage, and auth are declarations. runlot deploy reads them and creates any service that does not exist yet. This is the same place as a binding declaration in a wrangler config; there is no separate command or dashboard button to turn them on. Creation is idempotent, so deploying the same declaration many times still yields one service.
Removing a declaration does not remove the service. Removal is runlot pg delete, runlot storage delete, or runlot auth delete, each with a confirmation. auth requires a database, so "auth": true on its own creates the database as well.
Each service can be attached only once per project, so you declare it with true instead of a service name. In the worker they are env.db, env.storage, and env.auth.
Bundle manifest
runlot deploy does not upload this configuration file as is. The CLI generates a separate runlot.json manifest in the bundle that refers to the build output. You do not have to write it yourself, but the validation rules below apply.
| Field | Description |
|---|---|
main | The worker entry module included in the bundle. If it is absent, an entry point that serves static assets only is added automatically. |
assets | The assets directory included in the bundle. / and extensionless paths are answered with index.html, and the Content-Type is decided from the extension. |
notFound | 404 (default) or spa. With spa, extensionless paths are answered with /index.html. |
compatibilityDate | The format is YYYY-MM-DD. If it is not set, 2024-09-23 is used. |
compatibilityFlags | Compatibility flags, on an allow-list basis. The only value available at present is nodejs_compat. |
modules | The list of additional modules. Only the wasm type is supported. |
framework | The framework adapter. The only value supported at present is next. |
triggers | Scheduled execution. crons holds five-field cron expressions (UTC); they are parsed at deploy time and invalid ones are rejected. Requires main. |
compatibilityFlags is an allow-list because no manifest may enable a flag that grants user code control over the whole process. If the bundle imports a Node built-in module, nodejs_compat is required, so the CLI sets it automatically.
WASM can be included only through the modules field. workerd does not allow compiling inside the bundle by calling new WebAssembly.Module(bytes). The Prisma query compiler is affected by this constraint.
Bundle limits
| Item | Limit |
|---|---|
| Compressed upload size | 64 << 20 |
| Total size after decompression | 512 << 20 |
| Size of a single file | 64 << 20 |
| File count | 20_000 |
A bundle may contain regular files only. Symbolic links, paths that point outside the project root and duplicate entries are all rejected.