Environment Variables

Blitz comes with built-in support for environment variables, which allows you to do the following:

• Use .env* files to load environment variables
• Expose environment variables to the browser by prefixing with NEXT_PUBLIC_

Loading Environment Variables

Blitz has built-in support for loading environment variables from .env.local into process.env.

An example .env.local:

DB_HOST=localhost
DB_USER=myuser
DB_PASS=mypassword

This loads process.env.DB_HOST, process.env.DB_USER, and process.env.DB_PASS into the Node.js environment automatically allowing you to use them on the server.

Note: Blitz will automatically expand variables inside of your .env* files. This allows you to reference other secrets, like so:

# .env
HOSTNAME=localhost
PORT=8080
HOST=http://$HOSTNAME:$PORT

If you are trying to use a variable with a $ in the actual value, it needs to be escaped like so: \$.

For example:

# .env
A=abc
WRONG=pre$A # becomes "preabc"
CORRECT=pre\$A # becomes "pre$A"

Exposing Environment Variables to the Browser

By default all environment variables loaded through .env* files are only available in the Node.js environment, meaning they won't be exposed to the browser.

There are two ways you can expose a variable to the browser.

If you want to expose a variable to the browser, you can prefix it with NEXT_PUBLIC_. For example:

NEXT_PUBLIC_ANALYTICS_ID=abcdefghijk

The value will be inlined into JavaScript sent to the browser because of the NEXT_PUBLIC_ prefix.

// pages/index.js
import setupAnalyticsService from "../lib/my-analytics-service"

// NEXT_PUBLIC_ANALYTICS_ID can be used here as it's prefixed by NEXT_PUBLIC_
setupAnalyticsService(process.env.NEXT_PUBLIC_ANALYTICS_ID)

function HomePage() {
  return <h1>Hello World</h1>
}

export default HomePage

Different Values per Environment

In general only one .env.local file is needed. However, sometimes you might want to add some defaults for the development or production environment.

Blitz allows you to set defaults in .env (all environments), .env.development (development environment), .env.production (production environment), and .env.test (test environment). These files with defaults should be checked into git.

Appending .local will override the defaults. Examples: .env.local, .env.test.local. These files should not be checked into git.

Using custom environments

The three default environments are production, development, and test. However, sometimes, you need an additional environment, e.g. staging, to store env variables for it in a separate file. You can provide an app environment name by passing -e (--env) flag or setting APP_ENV directly. For example:

APP_ENV=staging blitz build

blitz prisma generate -e=staging

blitz dev --env staging

This will load additional env files: .env.<APP_ENV> and .env.<APP_ENV>.local.

If you need to load multiple env files, you can pass all the environments as comma-separated strings. For example:

blitz dev --env staging,production
# Loaded .env.staging.local
# Loaded .env.staging
# Loaded .env.production.local
# Loaded .env.production
# Loaded .env.local
# Loaded .env