Blitz is pivoting to framework agnostic toolkit. Click to learn more.
🚀Announcing Flightcontrol - Easily Deploy Blitz.js and Next.js to AWS 🚀
Back to Documentation Menu

Environment Variables


Jump to a Topic

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

Loading Environment Variables

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

An example .env.local:


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

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

For example:

# .env
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.

Option 1: BLITZ_PUBLIC_ Prefix

Prefix the variable with BLITZ_PUBLIC_ or NEXT_PUBLIC_. For example:


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

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

// BLITZ_PUBLIC_ANALYTICS_ID can be used here as it's prefixed by BLITZ_PUBLIC_

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

export default HomePage

Option 2: env in blitz.config.js

Any keys defined in env in your Blitz config will be inlined into JavaScript sent to the browser.

// blitz.config.js
module.exports = {
  // Env vars defined here will be PUBLIC and included in the client JS bundle
  env: {
    STRIPE_KEY: process.env.STRIPE_KEY,
    SENTRY_DSN: process.env.SENTRY_DSN,

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_NAME> and .env.<APP_NAME>.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

Idea for improving this page? Edit it on GitHub.