Applying the 'Environment Variable URL' Approach to Overcome Next.js Build-Time Environment Variable Limitations

Next.js's default dotenv approach substitutes environment variables at build time, requiring a separate build for each environment. This makes build artifacts dependent on specific environments and can reduce the reliability of build artifacts due to side effects from managing external modules like npm.

Next.js's Runtime Configuration feature supports runtime injection but is not compatible with SSG (Static Site Generation) and causes rendering and initialization overhead, so it is not recommended in the official documentation. Consequently, the team introduced the 'Environment Variable URL' approach to address these constraints.

Implementation

The Environment Variable URL approach involves generating a script file containing parsed environment variables accessible to the client and storing it in the public folder.

• Script Generation: Use find-up and dotenv to parse environment-specific .env files and generate an __ENV.js script in the /public folder that assigns them to the window.__ENV object.
• Server Integration: Copy the corresponding environment variables to a .env file for server-side use, making them accessible via process.env.
• Client Injection: Load the generated __ENV.js script in the Document component to inject it as a global variable.

With this approach, the client can access the same environment variables via window.__ENV and the server via process.env, eliminating build-time dependencies and enabling deployment to various environments from a single build artifact. This has resulted in reduced uncertainty in the build process and improved deployment reliability.