Environment Variables

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



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: NEXT_PUBLIC_ Prefix

Prefix the variable with

NEXT_PUBLIC_. For example:


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_
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: {

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.


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

Idea for improving this page?Edit it on GitHub
Bytes Newsletter