The source.include
is used to specify additional JavaScript files that need to be compiled.
To avoid redundant compilation, by default, Rsbuild only compiles JavaScript files in the current directory and TypeScript and JSX files in all directories. It does not compile JavaScript files under node_modules.
Through the source.include
config, you can specify directories or modules that need to be compiled by Rsbuild. The usage of source.include
is consistent with Rule.include in Rspack, which supports passing in strings or regular expressions to match the module path.
For example:
A typical usage scenario is to compile npm packages under node_modules, because some third-party dependencies have ESNext syntax, which may cause them to fail to run on low-version browsers. You can solve the problem by using this config to specify the dependencies that need to be compiled.
If you are unsure which third-party dependencies in node_modules contain ESNext syntax, you can use the Check Syntax Plugin of Rsbuild for checking. The plugin can help you find the modules that contain ESNext syntax.
Take query-string
as an example, you can add the following config:
The above two methods match the absolute paths of files using "path prefixes" and "regular expressions" respectively. It is worth noting that all referenced modules in the project will be matched. Therefore, you should avoid using overly loose values for matching to prevent compilation performance issues or compilation errors.
In the regular expression example above, we use [\\/]
to match the path separator because different operating systems use different path separators. Using [\\/]
ensures that the paths will match in both MacOS and Windows.
When you compile an npm package via source.include
, Rsbuild will only compile the matching module by default, not the Sub Dependencies of the module.
Take query-string
for example, it depends on the decode-uri-component
package, which also has ESNext code, so you need to add the decode-uri-component
package to source.include
as well.
When developing in Monorepo, if you need to refer to the source code of other libraries in Monorepo, you can add the corresponding library to source.include
:
If you match a module that is symlinked to the current project, then you need to match the real path of the module, not the symlinked path.
For example, if you symlink the packages/foo
path in Monorepo to the node_modules/foo
path of the current project, you need to match the packages/foo
path, not the node_modules/foo
path.
In general, source.include
should not be used to compile the entire node_modules
directory. For example, the following configuration is not recommended:
This is because most of the npm packages in node_modules
are already compiled, and it is usually unnecessary to recompile them. Compiling the entire node_modules
will increase compilation time and may cause unexpected errors in certain npm packages, such as core-js
, which may result in runtime exceptions after compilation.
If you are willing to accept the increase in compilation time, you can use the following configuration to compile all JavaScript files but exclude `core-js':