Environment Variables#

Modern.js provides support for environment variables, including built-in environment variables and custom environment variables.

Built-in Environment Variables#

ASSET_PREFIX#

The current path prefix of the asset, which is a read-only environment variable.

NODE_ENV#

The current execution environment and is a read-only environment variable whose have different values under different execution commands:

• production: Default value when running modern build or modern serve.
• development: Default value when running modern dev, also the default value in other cases.

MODERN_ENV#

Set the current execution environment manually. In addition to the values in the NODE_ENV, custom environment names are supported here, such as staging, boe, etc.

MODERN_TARGET#

When using @modern-js/runtime, Modern.js will automatically inject MODERN_TARGET to distinguish between SSR and CSR environments.

You can use process.env.MODERN_TARGET to determine the environment and execute appropriate code.

function App() {
  if (process.env.MODERN_TARGET === 'browser') {
    console.log(window.innerHeight);
  }
}

After the development build, you can see that the SSR and CSR bundles as follows:

// SSR bundles
function App() {
  if (false) {
  }
}

// CSR bundles
function App() {
  if (true) {
    console.log(window.innerHeight);
  }
}

This can provide different outputs for different environments to ensure that the bundle size is minimized. It can also be convenient to deal with some side effects for different environments.

Custom Environment Variables#

You can specify custom environment variables in both shell and .env files.

Via shell#

Add custom environment variables before the command:

REACT_APP_FOO=123 BAR=456 pnpm run dev

Via .env file#

Create a .env file in the project root and add custom environment variables, which are added to the Node.js process by default, for example:

REACT_APP_FOO=123
BAR=456

The .env file follows the following loading rules:

• .env: default.
• .env.{ MODERN_ENV | NODE_ENV }: Overrides .env for a specific environment.

When you need to use different config according to the environment, you can define environment variables in the .env file corresponding to the environment name, and manually set the execution environment when starting the project.

For example, when starting a project with the following command, the .env and .env.staging will load:

MODERN_ENV=staging pnpm run dev

Using Environment Variables#

Convention Names#

NODE_ENV can be used directly in front-end code. In addition, custom environment variables starting with MODERN_ can also be used directly in code.

For Example:

if (process.env.NODE_ENV === 'development') {
  // do something
}

After executing the pnpm run dev, you can see the following bundle:

if (true) {
  // do something
}

In custom HTML templates, you can also use such environment variables directly. For example, in config/html/head.html:

<meta name="test" content="<process.env.NODE_ENV>" />

Any Other Names#

If you need to use environment variables with any other names in your code, you can configure them in source.globalVars. For example:

export default defineConfig({
  source: {
    globalVars: {
      'process.env.VERSION': process.env.VERSION,
    }.
  },
});

At this point, the process.env.VERSION in the code will be replaced by the value of VERSION in the environment variables.

Use Global Replacement#

In addition to environment variables, Modern.js also supports replacing variables in code with other values or expressions, which can be used to distinguish between development environment and production environment in code.

For example, converts the expression TWO to 1 + 1:

export default {
  source: {
    define: {
      TWO: '1 + 1',
    },
  },
};

const foo = TWO;

// ⬇️ Turn into being...
const foo = 1 + 1;

In most cases, source.globalVars is already sufficient to replace variables. But the values passed in by source.globalVars will be serialized by JSON by default. So it cannot be replaced like 1 + 1 in the example above, at this time, we need to use source.define.