Populate your environment at runtime rather than build time.
- Isomorphic - Server and browser compatible (and even in middleware.)
- Static site generation support.
.env
support 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 supports 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 is
loaded by the browser and contains the environment variables. We generate this
file at runtime, so you don't have to declare your environment variables at
build time.
Our approach is compatible with static site generation, and it also supports middleware.
- Add the following lines to your
next.config.js
:
const { configureRuntimeEnv } = require('next-runtime-env/build/configure');
configureRuntimeEnv();
When the server starts, this 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 NodeJS.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. π