Registry / devops / next-runtime-env

next-runtime-env

library3.3.0jsnpmunverified

next-runtime-env is a crucial utility for Next.js applications, enabling the dynamic injection of environment variables at runtime rather than solely at build time. This capability is fundamental for adhering to the "build once, deploy many" philosophy, a cornerstone of continuous delivery and the twelve-factor methodology, which Next.js often lacks native support for in frontend contexts. The library allows developers to use the same build artifact across various environments, such as development, staging, and production, without the need for environment-specific rebuilds. The current stable version is `3.3.0`, with recent alpha and stable releases indicating active maintenance. It offers isomorphic design, ensuring seamless operation across server, browser, and middleware environments. Key differentiators include full compatibility with Next.js 13 and 14, and native support for `.env` files during development. The package maintains distinct major versions (1.x, 2.x, 3.x) to align with specific Next.js router types and major versions, providing tailored solutions for the Pages Router (1.x), Next.js 13 App Router (2.x), and Next.js 14 with enhanced caching (3.x).

devops

npm install next-runtime-env

github ↗package ↗

INSTALL

IMPORT

SIG · NEXT-RUNTIME-ENV

next-runtime-env

devopsjavascriptv3.3.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

PublicEnvScript

✓ import { PublicEnvScript } from 'next-runtime-env';

✗ import PublicEnvScript from 'next-runtime-env';

This is a named export. It must be placed in the `<head>` of your `app/layout.tsx` (App Router) or `pages/_document.tsx` (Pages Router) to expose environment variables client-side.

env

✓ import { env } from 'next-runtime-env';

✗ import env from 'next-runtime-env'; process.env.NEXT_PUBLIC_VAR;

The `env` function is a named export used in client components to access runtime-injected variables. Do not use `process.env` in client components for runtime variables as it will only reflect build-time values.

makeEnvPublic

✓ import { makeEnvPublic } from 'next-runtime-env';

✗ import makeEnvPublic from 'next-runtime-env';

This named export is used programmatically to expose additional, non-`NEXT_PUBLIC_` prefixed environment variables to the client-side runtime, requiring specific configuration.

This quickstart demonstrates how to configure `next-runtime-env` for a Next.js App Router project (v3.x), placing `PublicEnvScript` in `app/layout.tsx` to expose environment variables and then accessing them in a client component using the `env` function.

import { PublicEnvScript } from 'next-runtime-env'; import { env } from 'next-runtime-env'; import React, { useEffect, useState } from 'react'; // next.config.mjs (Optional, but recommended for Next.js 14 / v3.x) /** @type {import('next').NextConfig} */ const nextConfig = { experimental: { // This ensures next-runtime-env functions correctly with server components serverComponentsExternalPackages: ['next-runtime-env'], }, }; export default nextConfig; // app/layout.tsx // Place PublicEnvScript in the <head> of your root layout export default function RootLayout({ children, }: { children: React.ReactNode }) { return ( <html lang="en"> <head> <PublicEnvScript /> </head> <body> <h1>My Next.js Runtime Environment App</h1> {children} </body> </html> ); } // app/client-page.tsx (Example of consuming variables client-side) 'use client'; // Mark as a client component export default function SomePage() { const [fooEnv, setFooEnv] = useState<string | undefined>(); const [barEnv, setBarEnv] = useState<string | undefined>(); useEffect(() => { // Access variables using the 'env' function setFooEnv(env('NEXT_PUBLIC_FOO_RUNTIME')); setBarEnv(env('NEXT_PUBLIC_BAR_RUNTIME')); }, []); return ( <main style={{ padding: '20px', border: '1px solid #eee', margin: '20px' }}> <h2>Client-Side Runtime Variables</h2> <p>NEXT_PUBLIC_FOO_RUNTIME: {fooEnv ?? 'Not set'}</p> <p>NEXT_PUBLIC_BAR_RUNTIME: {barEnv ?? 'Not set'}</p> <p><em>To see these, ensure NEXT_PUBLIC_FOO_RUNTIME and NEXT_PUBLIC_BAR_RUNTIME are in your .env.local or deployment environment.</em></p> </main> ); } // Example .env.local file (for local development) // NEXT_PUBLIC_FOO_RUNTIME=hello-from-runtime-dev // NEXT_PUBLIC_BAR_RUNTIME=another-runtime-var-dev

Debug

Known issues

breakingnext-runtime-env has distinct major versions that are compatible with specific Next.js major versions and router types. Using an incompatible version will lead to unexpected behavior or breakage.

fix

Consult the `next-runtime-env` documentation for the correct version matching your Next.js setup: v1.x for Next.js 12/13 Pages Router, v2.x for Next.js 13 App Router, and v3.x for Next.js 14 App Router with improved caching.

affects: >=1.0

gotchaWhen using `next-runtime-env`, developers might mistakenly attempt to access runtime-injected environment variables via `process.env` in client-side code, which will only yield build-time values or `undefined`.

fix

Always use the `env('YOUR_VAR_NAME')` function provided by `next-runtime-env` within client components to correctly access environment variables exposed at runtime. `process.env` is only reliable for server-side or build-time variables.

affects: >=1.0

gotchaFor `next-runtime-env` v3.x and Next.js 14, specifically when using server components or a 'context approach', you might need to explicitly configure `next-runtime-env` in `serverComponentsExternalPackages` within `next.config.js`.

fix

Add `next-runtime-env` to the `experimental.serverComponentsExternalPackages` array in your `next.config.js` to ensure proper functionality and avoid potential issues with server-side rendering and hydration.

affects: >=3.2.2

Errors

Common errors & fixes

ReferenceError: process is not defined

Attempting to access `process.env.VAR_NAME` directly in a client-side component or browser environment where `process` is not available.

fix

For runtime-injected environment variables in client-side code, use `import { env } from 'next-runtime-env';` and then `env('YOUR_VAR_NAME')`.

Environment variables appear as `undefined` or empty strings on the client.

`PublicEnvScript` is not correctly rendered in the `<head>` of your root layout (`app/layout.tsx` for App Router or `pages/_document.tsx` for Pages Router), or variables are not prefixed with `NEXT_PUBLIC_` (or explicitly exposed).

fix

Ensure `PublicEnvScript` is present and correctly placed in the `<head>`. Verify that public variables are prefixed with `NEXT_PUBLIC_`. For non-public variables, follow the documentation on using `makeEnvPublic`.

Error: "next-runtime-env" is not compatible with Next.js X. Please use version Y. (or similar message indicating version mismatch)

The installed version of `next-runtime-env` does not match the major version of your Next.js project or its configured router type (Pages Router vs. App Router).

fix

Check the `next-runtime-env` compatibility guide in its README. For Next.js 12/13 Pages Router, use `next-runtime-env@1.x`. For Next.js 13 App Router, use `next-runtime-env@2.x`. For Next.js 14 App Router, use `next-runtime-env@3.x`.

Upgrade

Version history

3.3.0latest on npm

Audit

Dependencies

nextrequiredPeer dependency for Next.js framework integration.

reactrequiredPeer dependency for React component usage.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/expatfile/next-runtime-env ↗

packagehttps://www.npmjs.com/package/next-runtime-env ↗