Next.js Runtime Environment Configuration

3.3.0 · active · verified Tue Apr 21

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).

Common errors

Warnings

Install

Imports

Quickstart

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

view raw JSON →