Configuration
Environment variables
Configuration and secrets per project and environment, encrypted at rest, plus the variables the platform sets for you.
Add a variable
Open the project's Settings → Environment Variables and select Add environment variable (needs env:write). Enter:
- Key: letters, numbers and underscores, not starting with a number, up to 256 characters. Pasting
KEY=valueinto the key field fills both fields. - Value: up to 64 KB.
- Environments: Production, Preview, or both.
- Sensitive: on by default.
Variables apply to deployments created after you save. Running deployments keep the values they started with; redeploy to pick up a change.
Keys that differ only in letter case are the same variable: saving api_url replaces API_URL.
Import a .env file
Import takes pasted .env text and saves every variable in it at once, with the same environments and sensitivity:
- One
KEY=valueper line; anexportprefix is allowed. Blank lines and#comments are ignored. - Single- or double-quoted values can span lines; double quotes understand
\n,\t,\"and\\. - When a key appears twice, the last one wins.
- Up to 200 variables per import. Nothing is saved if any name is invalid or reserved.
Cloud → Settings → Environment Variables lists every project with a link to its variables.
Environments
| Environment | Used by |
|---|---|
| Production | Production deployments (builds of the production branch, and redeploys of them). |
| Preview | Preview deployments (every other branch). |
A promoted preview keeps its preview values. The API also accepts a development target, which no deployment uses.
Sensitive variables
A sensitive variable's value is never shown again, in Cloud or by the API (it's returned as null). To change a sensitive variable's environments, edit it and leave the value empty: the stored value is kept. A sensitive variable can be made visible only by entering a new value.
Values of variables that aren't sensitive can be revealed in Cloud by anyone with env:read.
Where variables are available
| Next.js | Static | |
|---|---|---|
| During the build | Yes | Yes |
| In the server function | Yes | (no server) |
Build-time availability is what lets NEXT_PUBLIC_* values reach client code; anything you reference in client code is public.
Platform variables
The platform sets these on every Next.js server function:
| Variable | Value |
|---|---|
SI_DEPLOYMENT_ID | The deployment's id (dpl_…). |
SI_CRON_SECRET | The project's cron secret. Crons send it in the x-si-cron header. It's created with the project's first deployment and doesn't change. |
SI_DATABASE_<NAME> | The table name of each database linked to the project. |
SI_DATABASE_<NAME>_REGION | That table's region. |
SI_BUCKET_<NAME> | The bucket name of each bucket linked to the project. |
SI_BUCKET_<NAME>_REGION | That bucket's region. |
CACHE_BUCKET_NAME, CACHE_BUCKET_KEY_PREFIX, CACHE_BUCKET_REGION | The Next.js incremental cache (Runtime and caching). |
NODE_ENV | production |
<NAME> is the storage's name in capitals, with every character other than letters and digits replaced by _: a database named app-data becomes SI_DATABASE_APP_DATA. Linking or unlinking storage takes effect on the next deployment.
Platform variables aren't set during the build.
Reserved names
Projects can't define:
- Names starting with
SI_orCODEBUILD_ ARTIFACTS_BUCKET,ASSETS_BUCKET,AWS_ACCESS_KEY,AWS_ACCESS_KEY_ID,AWS_DEFAULT_REGION,AWS_EXECUTION_ENV,AWS_LAMBDA_FUNCTION_MEMORY_SIZE,AWS_LAMBDA_FUNCTION_NAME,AWS_LAMBDA_FUNCTION_VERSION,AWS_LAMBDA_INITIALIZATION_TYPE,AWS_LAMBDA_LOG_GROUP_NAME,AWS_LAMBDA_LOG_STREAM_NAME,AWS_LAMBDA_RUNTIME_API,AWS_REGION,AWS_SECRET_ACCESS_KEY,AWS_SESSION_TOKEN,CACHE_BUCKET,LAMBDA_RUNTIME_DIR,LAMBDA_TASK_ROOT,_HANDLER,_X_AMZN_TRACE_ID
Encryption
Values are encrypted with a KMS key, bound to the organization and project, and decrypted only when a deployment builds or starts, or when Cloud shows a value that isn't sensitive. The build receives them as ordinary build environment variables.
Planned
- Organization-wide variables shared by every project. Coming soon
- Passing build values through Parameter Store instead of build environment variables. Coming soon