If there's information or certain behavior of your project that needs to differ depending on if it's running locally or on ZEIT Now, environment variables offer the perfect solution.
This document explores how you should look to define environment variables, before making them available in your project.
Defining Environment Variables
We recommend defining environment variables for each environment you wish to run your application in, using Now Secrets for cloud deployment and a .env
file for local development.
Cloud Deployment
To make sensitive information available to your project once deployed, we recommend using Now Secrets. By using Now Secrets, the data will be encrypted and stored securely, no longer directly accessible by anyone, and only exposed to deployments as environment variables.
To define a Now Secret, use the following command:
now secrets add <secret-name> <secret-value>
To remove a Now Secret, use the following command:
now secrets rm <secret-name>
To rename a Now Secret, use the following command:
now secrets rename <secret-name> <new-name>
Local Development
When developing locally, we recommend using a .env
file to define your environment variables. This provides a clear separation from your production secrets and provides you with a great deal of flexibility when changing environment variables during development.
You can also use a .env.build
file to make environment variables available to the build process of your application if required.
The syntax of a .env
file is simple as illustrated by the example below:
ENVIRONMENT_VARIABLE_NAME=environment-variable-value
Accessing Environment Variables
Regardless of whether you are using Now Secrets for a deployment or a .env
file for local development, there is a single, unified method to make environment variables accessible to your application.
To make your defined environment variables available to your application, create a now.json
file with an env
property like the example below:
{ "env": { "VARIABLE_NAME": "@environment-variable-name" } }
The above example will make the key VARIABLE_NAME
available to an application which will give access to the variable defined either as a Now Secret or inside a .env
file.
To use the environment variable from inside the application you would need to reference it using the correct syntax for the language being used. For example, using Node.js, the syntax would be:
process.env.VARIABLE_NAME
The syntax required to make the environment variable available inside the build process of your application is very similar and is shown below:
{ "build": { "env": { "VARIABLE_NAME": "@environment-variable-name" } } }
Built-In Variables
By default, all deployments expose the NOW_REGION
environment variable to Serverless Functions which provides the region that the lambda was deployed to.
Reserved Variables
The following environment variables are reserved and therefore unavailable for use:
AWS_REGION
AWS_DEFAULT_REGION
AWS_ACCESS_KEY_ID
AWS_SECRET_KEY
AWS_SECRET_ACCESS_KEY
AWS_EXECUTION_ENV
AWS_LAMBDA_LOG_GROUP_NAME
AWS_LAMBDA_LOG_STREAM_NAME
AWS_LAMBDA_FUNCTION_NAME
AWS_LAMBDA_FUNCTION_MEMORY_SIZE
AWS_LAMBDA_FUNCTION_VERSION
AWS_SESSION_TOKEN
NOW_REGION
TZ
_HANDLER
LAMBDA_TASK_ROOT
LAMBDA_RUNTIME_DIR
Using either, or any, of these as a name for your environment variables, will result in the deployment failing.