Populate your environment at runtime rather than build time.
- Isomorphic - Server and browser compatible (and even in middleware.)
- Static site generation support.
.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 generating a JavaScript file that
contains the environment variables at runtime, so you no longer have to declare
your environment variables at build time. This file is loaded in the client,
safely exposing those variables to the browser. This allows you to follow the
build once, deploy many principle by providing differed runtime variables to the
same build.
Our approach is compatible with static site generation and supports middleware.
For Next.js 13 App Router support, user next-runtime-env@2.0.0 or higher.
- Add the following lines to your
next.config.js:
const { configureRuntimeEnv } = require('next-runtime-env/build/configure');
configureRuntimeEnv();When the server starts, this
8000
generates an __ENV.js file in the public folder
containing allow-listed environment variables with a NEXT_PUBLIC_ prefix.
- Add the following to the head section of your
pages/_document.js:
// pages/_document.tsx
<script src="/__ENV.js" />This will load the generated file in the browser.
In the browser, your variables will now be available at
window.__ENV.NEXT_PUBLIC_FOO and on the server at
process.env.NEXT_PUBLIC_FOO. For example:
# .env
NEXT_PUBLIC_FOO="foo"
BAR="bar"
NEXT_PUBLIC_BAZ="baz"// pages/some-page.tsx
type Props = {
bar: string;
};
export default function SomePage({ bar }: Props) {
return (
<div>
{window.__ENV.NEXT_PUBLIC_FOO} {bar}
</div>
);
}
export const getStaticProps: GetStaticProps = async (context) => {
return {
props: {
bar: process.env.BAR,
},
};
};We have included some utility function to make it even easier to work with environment variables.
Returns the value of the environment variable with the given key. If the environment variable is not found, it returns undefined.
// pages/some-page.tsx
import { env } from 'next-runtime-env';
type Props = {
bar: string;
};
export default function SomePage({ bar }: Props) {
return (
<div>
{env('NEXT_PUBLIC_FOO')} {bar}
</div>
);
}
export const getStaticProps: GetStaticProps = async (context) => {
return {
props: {
bar: env('BAR'),
},
};
};Returns all environment variables as a ProcessEnv object regardless of
the platform. This is useful if you want to destructure multiple env vars at
once.
// pages/some-page.tsx
import { allEnv } from 'next-runtime-env';
type Props = {
bar: string;
};
export default function SomePage({ bar }: Props) {
const { NEXT_PUBLIC_FOO, NEXT_PUBLIC_BAZ } = allEnv();
return (
<div>
{NEXT_PUBLIC_FOO} {NEXT_PUBLIC_BAZ} {bar}
</div>
);
}
export const getStaticProps: GetStaticProps = async (context) => {
const { BAR } = allEnv();
return {
props: {
bar: BAR,
},
};
};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 { configureRuntimeEnv } = require('next-runtime-env/build/configure');
const { makeEnvPublic } = require('next-runtime-env/build/make-env-public');
// 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');
// Or you can make multiple env vars public at once.
makeEnvPublic(['BAR', 'BAZ']);
// This will generate the `__ENV.js` file and include `NEXT_PUBLIC_FOO`.
configureRuntimeEnv();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. 🙏