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>

Defining a Now Secret using Now CLI.

To remove a Now Secret, use the following command:

now secrets rm <secret-name>

Removing a Now Secret using Now CLI.

To rename a Now Secret, use the following command:

now secrets rename <secret-name> <new-name>

Renaming a Now Secret using Now CLI.

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

An example .env file.

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"
  }
}

An example now.json file that provides an application with a defined environment variable.

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

Accessing a defined environment variable from within a Node.js application.

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"
    }
  }
}

An example now.json file that provides an application's build process with a defined environment variable.

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.