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
TablePurposeDetails
[app]App name and deployed URLthis page
[vercel], [vercel.extra]Generated .nextrs/vercel.jsonthis page
[deploy]Env files nextrs deploy / nextrs cron deploy read credentials frombelow
[build]Replace the on-this-machine compile with your own commandCustom Build Command
[bundles.<name>], [deployment]Per-bundle Cargo features and runtime assetsServer 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 generate writes it when it is missing and removes it if you set git_deploys = true. It has no effect on nextrs 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.jsonnextrs.toml
regionsregions
installCommandinstall_command
buildCommandbuild_command
functions.api/index.rs.runtimeruntime
git.deploymentEnabledgit_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:

  1. .vercel/.env.<target>.local — what vercel pull / vercel env pull writes (nextrs deploy runs vercel pull itself, so this usually exists)
  2. .env.<target>.local
  3. .env.<target>
  4. .env.local
  5. .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"