nextrs.toml
Reference for every nextrs.toml table: app identity, Vercel settings, deploy env files (CRON_SECRET and tokens), custom build command, and server bundles
nextrs.toml at the app root is where a nextrs app is configured. It is
the one file you edit; nextrs generate turns it into the provider files
Vercel and Cloudflare actually read. Newly scaffolded apps ship with one.
[app]
name = "myapp" # names generated resources (myapp-cron)
url = "https://myapp.vercel.app" # the deployed app, for cron triggers
[vercel]
regions = ["pdx1"]
# runtime = "vercel-rust@4.0.11" # defaults, shown for reference
# install_command = "npm ci"
# build_command = "npm run client:prepare && cargo build --release --bin index && npm run client:build"
# git_deploys = false # false: root vercel.json turns off builds on push
# [vercel.extra] # non-framework Vercel keys only
# trailingSlash = false
# [deploy] # optional: where deploy reads credentials
# env_file = ".vercel/.env.production.local"
# [build] # optional: compile somewhere else
# command = "scripts/build-in-container.sh"
# [bundles.<name>] / [deployment] # optional: server bundles
| Table | Purpose | Details |
|---|---|---|
[app] | App name and deployed URL | this page |
[vercel], [vercel.extra] | Generated .nextrs/vercel.json | this page |
[deploy] | Env files nextrs deploy / nextrs cron deploy read credentials from | below |
[build] | Replace the on-this-machine compile with your own command | Custom Build Command |
[bundles.<name>], [deployment] | Per-bundle Cargo features and runtime assets | Server Bundles |
Unknown tables and keys are rejected, so a typo fails loudly instead of being ignored.
Cron schedules are colocated with their protected handlers as
#[nextrs::cron(schedule = "...")]; see Cron Jobs.
What nextrs generate writes
-
.nextrs/vercel.json— generated framework state containing the Rust function, the catch-all rewrite to it, immutable caching for/dist, git auto-builds off, your regions/commands, and any Vercel-provider crons. It is overwritten atomically on every generation and passed to Vercel with--local-config. The adjacent README marks it as generated.[vercel.extra]is an escape hatch for Vercel keys the table does not model, but cannot override framework-owned$schema, regions, commands, functions, headers, rewrites, git, or crons. -
.nextrs/cloudflare/— the Worker shim for cloudflare-provider crons (gitignored, regenerated on demand). -
vercel.json(app root, committed) — a stub holding one setting,"git": { "deploymentEnabled": false }. Vercel's Git integration reads only this file; it never sees the gitignored.nextrs/vercel.json. Without the stub every push starts a cloud build that cannot succeed, because the generated client is not in git.nextrs generatewrites it when it is missing and removes it if you setgit_deploys = true. It has no effect onnextrs deploy, which passes the generated file explicitly.
The [vercel] table is optional; omitting it uses framework defaults. The
root vercel.json is not a second source of deployment or cron
configuration: nextrs deploy never reads it, and generation only ever
writes or removes the stub. If the file holds anything else, generation
leaves it alone, warns, and explains how to move its settings into
nextrs.toml.
Moving settings from vercel.json
Copy settings that NextRS models into [vercel]:
vercel.json | nextrs.toml |
|---|---|
regions | regions |
installCommand | install_command |
buildCommand | build_command |
functions.api/index.rs.runtime | runtime |
git.deploymentEnabled | git_deploys |
Put other non-framework top-level settings under [vercel.extra]. For example,
"trailingSlash": false becomes:
[vercel.extra]
trailingSlash = false
Do not copy $schema, functions, headers, rewrites, git, crons, or
the other framework-owned keys listed above into [vercel.extra]; NextRS
generates those from its typed settings and route declarations. The original
file is left untouched.
nextrs deploy and nextrs cron deploy both run generate first, so the
provider files can't drift from the config.
Deploy env files
nextrs deploy and nextrs cron deploy need credentials such as
CRON_SECRET, CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID, and
VERCEL_TOKEN. You do not have to export them. Anything not already set in
the process environment is filled from env files in the app root —
target-specific files first, generic .env last, first hit wins per key:
.vercel/.env.<target>.local— whatvercel pull/vercel env pullwrites (nextrs deployrunsvercel pullitself, so this usually exists).env.<target>.local.env.<target>.env.local.env
<target> is production, or preview for nextrs deploy --preview; a
preview deploy never reads production files. A variable already set in the
process environment always wins, so CI secret stores keep working. Values are
never printed — only how many variables were loaded.
To be explicit, name the file or a list of files. This replaces the search above, and a file that does not exist is an error:
[deploy]
env_file = ".vercel/.env.production.local"
# env_file = ["secrets/deploy.env", ".env"] # first wins per key
If a credential is still missing, the error lists every path searched:
nextrs: Cloudflare cron routes are configured, but CRON_SECRET is not set.
searched:
.vercel/.env.production.local (not found)
.env.production.local (not found)
.env.production (not found)
.env.local (not found)
.env (no CRON_SECRET)
Server bundle settings
Colocated bundle.toml files assign routes and subtrees. [bundles.<name>] in
nextrs.toml supplies the named bundle's Cargo features and private runtime
assets; [deployment].features supplies common features. See
Server Bundles for the complete build and deploy flow.
Custom build command
[build] command makes nextrs deploy run your command instead of compiling
the server bundles on this machine — for apps that link native system
libraries and must build in a container. nextrs verifies the output before
uploading. See Custom Build Command.
[build]
command = "scripts/build-in-container.sh"