Next.js Environment Configuration

Manage environment variables, runtime config, and server-only module boundaries safely

When to Use

• Configuring API keys, database URLs, and secrets for server-side code
• Exposing safe configuration values to the browser via

  NEXT_PUBLIC_

  prefix
• Validating environment variables at build time to catch misconfiguration early
• Preventing server-only secrets from leaking into the client bundle
• Configuring different behavior for development, staging, and production environments

Instructions

1. Prefix environment variables with

   NEXT_PUBLIC_

   to expose them to the browser — all other variables are server-only.
2. Never put secrets (API keys, database URLs, private keys) in

   NEXT_PUBLIC_

   variables — they are inlined into the client bundle.
3. Use

   t3-env

   or

   @t3-oss/env-nextjs

   to validate environment variables at build time with Zod schemas.
4. Create

   src/env.ts

   (or

   lib/env.ts

   ) as the single source of truth for env var access — import env values from here, never from

   process.env

   directly in components.
5. Add

   import 'server-only'

   to any module that accesses server-only env vars to prevent accidental client import.
6. Use

   .env.local

   for local development secrets — it is gitignored by default. Use

   .env.development

   and

   .env.production

   for non-secret environment-specific values.
7. Wrap

   next.config.ts

   with your env validation so the build fails immediately on missing required variables.
8. Access runtime environment variables in

   next.config.ts

   via

   process.env

   — variables set in hosting dashboards (Vercel, Railway) are available at runtime.

// src/env.ts — validated env with t3-env
import { createEnv } from '@t3-oss/env-nextjs';
import { z } from 'zod';

export const env = createEnv({
  server: {
    DATABASE_URL: z.string().url(),
    NEXTAUTH_SECRET: z.string().min(32),
    STRIPE_SECRET_KEY: z.string().startsWith('sk_'),
  },
  client: {
    NEXT_PUBLIC_APP_URL: z.string().url(),
    NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY: z.string().startsWith('pk_'),
  },
  runtimeEnv: {
    DATABASE_URL: process.env.DATABASE_URL,
    NEXTAUTH_SECRET: process.env.NEXTAUTH_SECRET,
    STRIPE_SECRET_KEY: process.env.STRIPE_SECRET_KEY,
    NEXT_PUBLIC_APP_URL: process.env.NEXT_PUBLIC_APP_URL,
    NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY: process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY,
  },
});

// lib/db.ts — import 'server-only' prevents client bundle inclusion
import 'server-only';
import { env } from '@/env';
import { drizzle } from 'drizzle-orm/postgres-js';
import postgres from 'postgres';

const client = postgres(env.DATABASE_URL);
export const db = drizzle(client);

Details

Next.js treats environment variables differently depending on when and where they are accessed:

Build-time inlining:

NEXT_PUBLIC_

variables are replaced with their literal values at build time (

process.env.NEXT_PUBLIC_API_URL

becomes

"https://api.example.com"

in the bundle). This means the value is fixed at build time and cannot change at runtime without rebuilding.

Server-only variables: Variables without

NEXT_PUBLIC_

are only available in Server Components, Route Handlers, and other server-side code. Accessing them in a Client Component returns

undefined

and does not leak the value — it simply does not work.

.env

file priority: Next.js loads

.env

,

.env.local

,

.env.development

/

.env.production

, and

.env.development.local

/

.env.production.local

. More specific files override less specific ones.

.local

files take highest priority and should be in

.gitignore

.

Runtime vs build-time: Variables set in the Vercel dashboard are available at runtime in server-side code. However,

NEXT_PUBLIC_

variables must be set at build time in Vercel — setting them in the dashboard alone requires a rebuild.

t3-env benefits: Without validation, a missing

DATABASE_URL

crashes the app at the first database query — potentially after deployment.

t3-env

fails the build or server startup immediately with a clear error listing every missing or invalid variable.

server-only

package:

import 'server-only'

causes a build error if the module is imported in a Client Component. Use it in any module that accesses secrets, database clients, or other server-only resources. Pair with

client-only

for the inverse — marking browser-only modules.

Source

https://nextjs.org/docs/app/building-your-application/configuring/environment-variables

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.