Next.js - Environment Variables

Next.js provides built-in support for environment variables, allowing you to manage configuration settings like API keys, database credentials, or feature flags without hardcoding them into your application.

Environment variables are typically defined in .env files in your project’s root directory.

.env.local: Default values for all environments. This file should be added to .gitignore as it might contain sensitive secrets.
.env.development: Variables specific to the development environment (npm run dev).
.env.production: Variables specific to the production environment (npm run build, npm run start).
.env: Default values (committed to git, should not contain secrets).

Next.js loads variables from these files based on the current environment. .env.local always overrides defaults, and environment-specific files (.env.development, .env.production) override .env.local.

Creating `.env.local`

Create a file named .env.local in your project root with the following example content:

# Database Credentials (Server-Side Only)
DB_HOST=localhost
DB_USER=myuser
DB_PASS=supersecretpassword

# Public API Key (Client-Side Accessible)
NEXT_PUBLIC_ANALYTICS_ID=G-XYZ123ABC

# Feature Flag
ENABLE_BETA_FEATURE=true

Important Security Note: By default, environment variables defined in .env files are only available on the server-side (in Server Components, Route Handlers, or server-side data fetching functions). To expose a variable to the browser (for use in Client Components), you must prefix it with NEXT_PUBLIC_.

Accessing Environment Variables

You can access environment variables using process.env.VARIABLE_NAME.

Let’s create a page component (app/config-demo/page.tsx) to demonstrate accessing both server-side and client-side variables. Since we need to show a client-side variable, we’ll create a separate Client Component.

Create the Client Component (app/config-demo/client-config-display.tsx):

'use client'; // Mark this as a Client Component

export default function ClientConfigDisplay() {
  // Access the public environment variable
  const analyticsId = process.env.NEXT_PUBLIC_ANALYTICS_ID;

  return (
    <div>
      <h3>Client-Side Configuration</h3>
      <p>Analytics ID: {analyticsId || 'Not Set'}</p>
      {/* Trying to access DB_HOST here would result in 'undefined' */}
      {/* <p>DB Host (Client Attempt): {process.env.DB_HOST}</p> */}
    </div>
  );
}

Create the main Page Component (app/config-demo/page.tsx):

import ClientConfigDisplay from './client-config-display';

export default function ConfigDemoPage() {
  // Access server-side environment variables directly
  const dbHost = process.env.DB_HOST;
  const dbUser = process.env.DB_USER;
  // Note: Avoid rendering sensitive variables like passwords directly!
  // const dbPass = process.env.DB_PASS;
  const isBetaEnabled = process.env.ENABLE_BETA_FEATURE === 'true';

  return (
    <main>
      <h1>Environment Variable Demo</h1>

      <h2>Server-Side Configuration</h2>
      <p>Database Host: {dbHost || 'Not Set'}</p>
      <p>Database User: {dbUser || 'Not Set'}</p>
      <p>Beta Feature Enabled: {isBetaEnabled ? 'Yes' : 'No'}</p>

      <hr style={{ margin: '20px 0' }} />

      {/* Render the Client Component */}
      <ClientConfigDisplay />
    </main>
  );
}

When you run npm run dev, Next.js automatically loads variables from .env.local.

npm run dev
# ... server startup messages ...
# You might see a line like:
# info  - Loaded env from /path/to/your/project/.env.local

Verify Output

Open http://localhost:3000/config-demo in your browser. You should see the values from your .env.local file displayed:

The ‘Server-Side Configuration’ section will show the DB_HOST, DB_USER, and beta feature status. The ‘Client-Side Configuration’ section (rendered by the Client Component) will show the NEXT_PUBLIC_ANALYTICS_ID. Note that the server-only variables like DB_HOST are not accessible in the Client Component.

Next.js - Environment Variables

Next.js - Environment Variables

Creating .env.local

Accessing Environment Variables

Verify Output

Creating `.env.local`