Populate your environment at runtime rather than build time.
- Isomorphic - Server and browser compatible (and even in middleware.)
- Next.js 13 App Router compatible.
.envsupport during development, just like Next.js.
Build once, deploy many is an essential principle of software development. The main idea is to use the same bundle for all environments, from testing to production. This approach enables easy deployment and testability and is considered a fundamental principle of continuous delivery. It is also part of the twelve-factor methodology. As crucial as it is, it has yet to receive significant support in the world of front-end development, and Next.js is no exception.
Next.js does support environment variables, but only at build time. This means you must rebuild your app for each target environment, which violates the principle. But what if you want, or need, to follow the build once, deploy many principle?
next-runtime-env solves this problem by creating a context that exposes your environment variables at runtime, so you no longer have to declare
your environment variables at build time. The context provider safely exposes all environment variables prefixed with NEXT_PUBLIC_ to the browser. This allows you to follow the build once, deploy many principle by providing differed runtime variables to the same build.
Because next-runtime-env is build on top of server components it is only compatible with Next.js 13 App Router. Use version 1.x for Next.js 13 Page Router support.
Add the following lines to your app/layout.tsx:
// app/layout.tsx
import { PublicEnvProvider } from 'next-runtime-env';
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<html lang="en">
<body>
<PublicEnvProvider>{children}</PublicEnvProvider>
</body>
</html>
);
}
// By default server components are statically generated at build-time. To make
// sure the env vars are actually loaded use, add the following line to server
// components that use [env]. 👇
export const dynamic = 'force-dynamic';The PublicEnvProvider will automatically expose all environment variables prefixed with NEXT_PUBLIC_ to the context. If you want more control over which variables are exposed to the context, you can use the EnvProvider and define the exposed variables manually.
In the browser your environment variables are now accessible using the useEnvContext hook. On the server you can use process.env because the layout is forced to be dynamic. For example:
# .env
NEXT_PUBLIC_FOO="foo"
BAR="bar"A
.envfile is not required, you can also declare your environment variables in whatever way you want.
// app/client-page.tsx
'use client';
import { useEnvContext } from 'next-runtime-env';
export default function SomePage() {
const { NEXT_PUBLIC_FOO } = useEnvContext();
return (
<main >
NEXT_PUBLIC_FOO: {NEXT_PUBLIC_FOO}
</main>
);
}// app/server-page.tsx
export default function SomePage() {
return (
<main >
BAR: {process.env.BAR}
</main>
);
}We have included some utility function to make it even easier to work with environment variables.
Makes an environment variable with a given key public. This is useful if you
want to use an environment variable in the browser, but it was was not declared
with a NEXT_PUBLIC_ prefix.
For ease of use you can also make multiple env vars public at once by passing an array of keys.
// next.config.js
const { makeEnvPublic } = require('next-runtime-env');
// Given that `FOO` is declared as a regular env var, not a public one. This
// will make it public and available as `NEXT_PUBLIC_FOO`.
makeEnvPublic('FOO');
8DFE
// Or you can make multiple env vars public at once.
makeEnvPublic(['BAR', 'BAZ']);This package is maintained and actively used by Expatfile.tax. The #1 US expat tax e-filing software. 🇺🇸
Big thanks to the react-env project, which inspired us. 🙏 Also, a big shout out to @andonirdgz for the idea to use a context provider. 💪