Next.js Public Runtime Environment

next-public-env is a lightweight utility that dynamically injects environment
variables into your Next.js application at runtime instead of just at build time.

The Problem

Next.js's standard approach bakes environment variables into your application
during the build process through NEXT_PUBLIC_ variables. This means you need a
separate build for each environment; one for development, another for staging,
and yet another for production. This violates the "build once, deploy many"
principle and creates unnecessary complexity in your deployment pipeline.

Features

- Type Safety & Validation: Integrates with Zod for schema validation, type
coercion, and full TypeScript support.
- Error-Resilient: Environment variables remain accessible even when pages
throw unhandled errors.
- Universal API: Use the same getPublicEnv() function in both Server and
Client Components.
- Lightweight: Adds only ~275 bytes to your client bundle.

Installation

Install it via your preferred package manager:

``bash
yarn add next-public-env
`
`bash
pnpm add next-public-env
`
`bash
npm install next-public-env
`

Getting Started

$3

Create a file to configure your public environment variables (e.g.,
public-env.ts).

Basic (Type-Safe):
`ts
// public-env.ts
import { createPublicEnv } from 'next-public-env';

export const { getPublicEnv, PublicEnv } = createPublicEnv({
NODE_ENV: process.env.NODE_ENV,
API_URL: process.env.API_URL,
MAINTENANCE_MODE: process.env.MAINTENANCE_MODE === 'true',
});
`

With Zod Validation (Recommended):
`ts
// public-env.ts
import { createPublicEnv } from 'next-public-env';

export const { getPublicEnv, PublicEnv } = createPublicEnv(
{
NODE_ENV: process.env.NODE_ENV,
API_URL: process.env.API_URL,
MAINTENANCE_MODE: process.env.MAINTENANCE_MODE,
PORT: process.env.PORT,
},
{
schema: (z) => ({
NODE_ENV: z.enum(['development', 'production', 'test']),
API_URL: z.string().url(),
MAINTENANCE_MODE: z.enum(['on', 'off']).default('off'),
PORT: z.coerce.number().default(3000), // Converts string to number
}),
}
);
`

$3

Place in your root layout to make variables available
client-side:

`tsx
// app/layout.tsx
import { PublicEnv } from './public-env';

export default function RootLayout({ children }: { children: React.ReactNode }) {
return (



{children}


);
}
`

$3

Access your environment variables with full type safety:

`tsx
// Server Component
import { getPublicEnv } from './public-env';

export default function ServerPage() {
const env = getPublicEnv();
return

When you use getPublicEnv() in a Server Component, that route automatically
switches to dynamic rendering. This ensures your environment variables are
always read fresh from the server at request time, rather than being cached at
build time.

$3

For specific use cases, you can override this behavior using the
dynamicRendering option. Set it to 'manual' to disable the automatic
noStore() call and take full control of your routes' rendering behavior.

Cache Components Support

Next.js Cache Components (enabled via cacheComponents: true in
next.config.js) prerender routes into a static HTML shell by default. This
means that environment variables are read at build time, which defeats the
purpose of next-public-env.

To ensure your environment variables are read at runtime, you must opt-out of
the static shell by making your component dynamic. You can do this by using any
runtime API(like
headers(), cookies(), etc.) or by using the getPublicEnvAsync() function
provided by this library which automatically calls await connection() to
opt-out of the static shell.

$3

getPublicEnvAsync() is a helper function that automatically calls await
connection() to opt-out of the static shell and returns your environment
variables.

> Important: Components using getPublicEnvAsync() (or any runtime API)
> should be wrapped in a boundary to allow the rest of the page to be
> prerendered.

`tsx
import { Suspense } from 'react';
import { getPublicEnvAsync } from './public-env';

async function EnvComponent() {
const env = await getPublicEnvAsync();
return