Environment Variables

Environment variables in next.js can be defined in .env files.

Next.js provides the following hierarchy based on NODE_ENV:

.env.$(NODE_ENV).local
.env.local (Not checked when NODE_ENV is test.)
.env.$(NODE_ENV)
.env

info

The NODE_ENV variable only allows the values production, development and test.

The recommended way to setup environment variables in Assemble Web is to use

• .env.production: Used for production builds
• .env.development: Used for dev work
• .env.test: Used when tests are run

Those files should be added in source control. If you need to override the values temporary for local work, you can create your own .env.local file

warning

Files ending with .local should NOT be committed to source control and should be used only for local development.

Usage of environment variables

In javascript/typescript you can access the environment variable through the global variable process.env.

const my_var = process.env.MY_VAR;

Next.js can expand variables at compile time if used in the format process.env.MY_VAR.

This feature can be useful to remove blocks of code when expression is resolved at compile time.

if (process.env.MY_VAR === 'value') {
  // ...
}

If the value of process.env.MY_VAR is not equal to the string 'value'. The code will be optimized by removing the block of code.

This behavior can be prevented by access the value dynamically

const { MY_VAR } = process.env;
// or
const key = 'MY_VAR';
const my_var = process.env[key];

Using environment variables in the Client

Next.js limits the environment variables exposed to client components. To access an environment variable from the client the variable needs to be prefixed with NEXT_PUBLIC_.

Available environment variables

Assemble Web implements the following environment variables

Variable	Description
DETAIL_IMAGE_QUALITY	Value for DetailImage component
NEXT_PUBLIC_BASE_URL	Url used by the application
SESSION_KEY	Secret key used to sign the session (User's authenticated state)
NEXT_PUBLIC_UNIFIED_API_BASE_URL	Required base URL of the Unified CMS+Config API
appIdGidEasterEggActive	Fallback for feature flag. Enable easter egg in appIdGid
debugOverlayVisible	Fallback for feature flag. Enables debug overlay
SUBSCRIPTION_STEPS	Number of steps in the subscription flow
NEXT_PUBLIC_GTM_ID	Optional public Google Tag Manager web container ID
NEXT_PUBLIC_RECAPTCHA_ENABLED	Whether to enable reCAPTCHA on the client side
NEXT_PUBLIC_RECAPTCHA_KEY	reCAPTCHA site key used for client-side integration
NEXT_PUBLIC_RECAPTCHA_MIN_SCORE	reCAPTCHA minimum score
RECAPTCHA_SECRET	reCAPTCHA site secret used for server-side validation
CONTENT_SECURITY_POLICY_REPORT_ONLY	Flag to set Content Security Policy report to report-only mode flow
CONTENT_SECURITY_POLICY_REPORT_URI	Optional absolute URL to receive CSP violation reports

At runtime, NEXT_PUBLIC_UNIFIED_API_BASE_URL is the only required middleware base URL. Assemble Web bootstraps the CMS configuration from that endpoint and resolves downstream service URLs from assembleConfig.servicesConfig. The six service-specific base URL variables are retained only as optional fallbacks for local development and tests.

note

Variables that work as a fallback for feature flags need to be named equally to the feature flag.

Adding strongly types environment variables

New environment variables can have type information by declaring them in environment-variables.d.ts. Additional information can be added as jsdoc comments.