Using Environment Variables in Next.js – Secure Loading, Browser Access, and Runtime Configuration

Loading Environment Variables

Next.js automatically loads environment variables from .env* files into process.env. Example:

# .env
DB_HOST=localhost
DB_USER=myuser
DB_PASS=mypassword

These variables are available in the Node.js environment, such as in Route Handlers:

export async function GET() {
  const db = await myDB.connect({
    host: process.env.DB_HOST,
    username: process.env.DB_USER,
    password: process.env.DB_PASS,
  })
}

Multiline Variable Support

You can define multiline secrets using line breaks or \n:

PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nKh9NV...\n-----END DSA PRIVATE KEY-----"

Loading Outside Next.js Runtime with @next/env

To load variables in config files or test runners, use the @next/env package:

import { loadEnvConfig } from '@next/env'

const projectDir = process.cwd()
loadEnvConfig(projectDir)

Referencing Other Variables

You can reference other variables using $:

# .env
TWITTER_USER=nextjs
TWITTER_URL=https://x.com/$TWITTER_USER

To use $ literally, escape it with \$.

Browser Access with NEXT_PUBLIC_

To expose a variable to the browser, prefix it with NEXT_PUBLIC_:

NEXT_PUBLIC_ANALYTICS_ID=abcdefghijk

It will be inlined into the JavaScript bundle at build time:

setupAnalyticsService(process.env.NEXT_PUBLIC_ANALYTICS_ID)

Note: Dynamic references like process.env[varName] won’t be inlined.

Runtime Environment Variables

During dynamic rendering, you can access variables at runtime:

export default async function Component() {
  await connection()
  const value = process.env.MY_VALUE
}

This is useful for Docker images promoted across multiple environments.

Environment Variables in Testing

Use .env.test for test-specific variables. .env.local is ignored in test mode to ensure consistency.

To load variables during tests:

import { loadEnvConfig } from '@next/env'

export default async () => {
  const projectDir = process.cwd()
  loadEnvConfig(projectDir)
}

Environment Variable Load Order

Variables are resolved in the following order:

1. process.env
2. .env.$(NODE_ENV).local
3. .env.local (ignored in test)
4. .env.$(NODE_ENV)
5. .env

For example, if NODE_ENV is development, .env.development.local takes priority.

Good to Know

• .env files must be in the root directory, not inside /src
• If NODE_ENV is unset, Next.js defaults to development for next dev and production otherwise
• .env.local files should be gitignored and not committed

Conclusion

Environment variables in Next.js offer a secure and flexible way to manage configuration across environments. By using .env files, NEXT_PUBLIC prefixes, and runtime access, you can build scalable and secure applications with ease.