Rsbuild supports injecting environment variables or expressions into the code during compilation, which is helpful for distinguishing the running environment or injecting constant values. This chapter introduces how to use environment variables.
By default, Rsbuild will automatically set the process.env.NODE_ENV
environment variable to 'development'
in development mode and 'production'
in production mode.
You can use process.env.NODE_ENV
directly in Node.js and in the runtime code.
In the development environment, the above code will be compiled as:
In the production environment, the above code will be compiled as:
After code minification, if (false) { ... }
will be recognized as invalid code and removed automatically.
You can use process.env.ASSET_PREFIX
in the runtime code to access the URL prefix of static assets.
assetPrefix
to make string concatenation easier.For example, we copy the static/icon.png
image to the dist
directory through output.copy configuration:
Then we can access the image URL in the runtime code:
In the development environment, the above code will be compiled as:
In the production environment, the above code will be compiled as:
By configuring the source.define, you can replace expressions with other expressions or values in compile time.
Define
looks like macro definitions in other programming languages. But JavaScript has powerful runtime capabilities, so you don't need to use it as a complicated code generator. You can use it to pass simple data, such as environment variables, from compile time to runtime. Almost there, it can be used to work with Rsbuild to shake trees.
The most basic use case for Define
is to replace expressions in compile time.
The value of the environment variable NODE_ENV
will change the behavior of many vendor packages. Usually, we need to set it to production
.
Note that the value provided here must be a JSON string, e.g. process.env.NODE_ENV
with a value of "production"
should be passed in as "\"production\""
to be processed correctly.
Similarly { foo: "bar" }
should be converted to "{\"foo\":\"bar\"}"
, which if passed directly into the original object would mean replacing the expression process.env.NODE_ENV.foo
with the identifier bar
.
For more about source.define
, just refer to API References.
The environment variable NODE_ENV
shown in the example above is already injected by the Rsbuild, and you usually do not need to configure it manually.
When using source.define
, please avoid injecting the entire process.env
object, e.g. the following usage is not recommended:
If the above usage is adopted, the following problems will be caused:
process.env
code will be replaced by a complete environment variable object, the bundle size of the front-end code will increase and the performance will decrease.So please avoid full injection, just inject the used variables from process.env
.
Note that source.define
will only match the full expression; destructing the expression will prevent the Rsbuild from correctly recognizing it.
When you read an environment variable in a TypeScript file, TypeScript may prompt that the variable lacks a type definition, and you need to add the corresponding type declaration.
For example, if you reference a CUSTOM_VAR
variable, the following prompt will appear in the TypeScript file:
To fix this, you can create a src/env.d.ts
file in your project and add the following content:
Define
can also be used to mark dead code to assist the Rsbuild with Tree Shaking optimization.
Build artifacts for different regions is achieved by replacing process.env.REGION
with a specific value, for example.
For an internationalized app:
Specifying the environment variable REGION=sg
and then executing build will eliminate any dead code.
Unused components are not bundled into the artifacts, and their external dependencies can be optimized accordingly, resulting in a destination with better size and performance.