next-runtime-env

next-runtime-env solves a specific gap in Next.js: environment variables are normally baked in at build time, which breaks the “build once, deploy many” workflow that most CI/CD pipelines rely on. The library injects a script tag into the document head that sets window.__ENV with the current process environment at request/render time, then exposes that data to both server and client code through a PublicEnvScript component, a React context provider (EnvProvider/useEnvContext), and a simple env() accessor function.

Because the values are resolved when the container actually starts rather than when the image is built, the same compiled Next.js bundle can be promoted from staging to production (or across regions) without a rebuild — each environment just supplies its own variables at runtime. The package tracks Next.js’s App Router evolution closely, with major versions pinned to Next.js 12/13/14 Pages vs. App Router support, and is maintained by Expatfile.tax as part of their production deployment pipeline.

What You Get

• PublicEnvScript — a drop-in component for app/layout.tsx that serializes all NEXT_PUBLIC_-prefixed variables into an inline script executed before hydration
• env() — an isomorphic accessor that reads from window.__ENV on the client and falls back to process.env on the server, so the same call works in both contexts
• EnvProvider and useEnvContext — a React context-based alternative for apps that prefer passing environment values explicitly through the component tree
• makeEnvPublic — a utility for exposing specific non-prefixed variables to the browser without renaming them
• Configurable nonce support and an option to disable Next.js’s <Script> wrapper in favor of a plain <script> tag, for compatibility with tools like Sentry that can race the Script component’s execution timing

Common Use Cases

• Deploying the same Docker image or build artifact to multiple environments (dev/staging/prod) with environment-specific configuration supplied only at container start
• Injecting runtime-determined values (feature-flag endpoints, region-specific API base URLs) into client components without rebuilding the app
• Reading environment variables inside Next.js middleware or edge functions where standard build-time inlining doesn’t apply
• Avoiding the need for a separate .env file per deployment target in Kubernetes/Docker-based CI pipelines

Under The Hood

Architecture — The library has three parallel surfaces that all funnel through the same runtime-injected global: src/script/ builds the PublicEnvScript/EnvScript component that serializes process.env (filtered to NEXT_PUBLIC_-prefixed keys via getPublicEnv()) into an inline <script> tag setting window.__ENV, src/provider/ offers a React-context (EnvProvider/useEnvContext) alternative for apps that want explicit prop-drilling instead of a global, and src/utils/make-env-public.ts covers the escape hatch for non-prefixed variables. All three converge on the same ProcessEnv typing in src/typings/process-env.ts, keeping the public API surface small and consistent. Tech Stack — Pure TypeScript with next (^14) and react (^18) as peer dependencies, built with tsc, tested with Jest plus @testing-library/react/jsdom, and released via semantic-release; there are no runtime dependencies beyond a small vendored picocolors copy for CLI-style log coloring. Code Quality — Nearly every source file under src/ has a co-located .spec.ts/.spec.tsx file (env-provider, use-env-context, make-env-public, env-script, public-env-script, get-public-env, log), giving the small surface area strong test coverage; ESLint is configured with the Airbnb base config plus simple-import-sort and Prettier integration, and TypeScript types are threaded consistently through props and hook return values. API Design — The public API is deliberately minimal: one component for script injection, one hook/provider pair for context-based access, and one plain env() function that works isomorphically on server and client, which keeps the learning curve low and integration into an existing app/layout.tsx a two-line change; inline JSDoc usage examples on every exported symbol further reduce onboarding friction.