Cedric Delacombaz

Cedric Delacombaz

Environment variables in Next.js

Build-time environment variables

Build-time | Official docs

Next comes with built-in support for .env files. It allows you to set defaults in

  • .env (all environments)
  • .env.development (development environment - when running next run dev)
  • .env.production (production environment - when running next start)

All of the above should be committed to source control and must not contain any secrets.

  • .env.local (all environments)
  • .env.development.local (development environment - when running next run dev)
  • .env.production.local (production environment - when running next start).

.env.$(NODE_ENV).local will have priority over non-local files. They can contain secrets and must not be committed to source control.

Secrets

Secrets can be set in .env.local for local development. For variables used on a server, they can be injected through CI/CD pipeline and used during build time.

Usage

Variables are loaded into the Node.js environment automatically, allowing you to use them in Next.js data fetching methods and API routes.

const SECRET_KEY = process.env.SECRET_KEY

Expose to browser

To make variables available in the browser, the variable names should be prepended with NEXT_PUBLIC_.

For example:

NEXT_PUBLIC_ANALYTICS_ID=12XyZ4!

Run-time environment variables

Runtime | Official docs

Generally you'll want to use build-time environment variables to provide your configuration. The reason for this is that runtime configuration adds rendering / initialization overhead and is incompatible with Automatic Static Optimization.

In case you really need to use runtime configuration, for example if you don't want to have any secrets visible in your CI/CD pipeline, you can do so by adding your environment variables directly on the server and also using the next.config.js to configure the variables.

module.exports = {
  serverRuntimeConfig: {
    // Will only be available on the server side
    mySecret: 'secret',
    secondSecret: process.env.SECOND_SECRET, // Pass through env variables
  },
  publicRuntimeConfig: {
    // Will be available on both server and client
    staticFolder: '/static',
  },
}

Conclusion

If you want to restrict access to secrets to only people having access to the server, you can use run-time environment variables. As long as it is ok for you, not being able to use Automatic Static Optimization.

If you want to take advantage of static site performance, you should use build-time environment variables. To protect secrets, in Gitlab CI/CD for example, you can make use of the different roles/permissions to restrict access to the variables. The variables can also be restricted to protected branches and even be masked, in order to not appear in logs.

If that's not enough, there is also a more complicated setup where you could retrieve secrets from a Vault.

GitLab environment variables demystified

← Back to home