Build FAQ#

If you encounter any build-related issues, you can refer to the current document for troubleshooting.

Rsbuild FAQ#

Modern.js is internally based on Rsbuild and encapsulates its own build tool, so you can directly refer to the FAQ document of Rsbuild:

• Rsbuild - Features FAQ

• Rsbuild - Exceptions FAQ

• Rsbuild - HMR FAQ

How to clear the webpack cache?#

By default, Modern.js's webpack cache is generated in the ./node_modules/.cache/webpack directory.

If you need to clear the local webpack cache, you can execute the following command:

rm -rf ./node_modules/.cache

How to view the final generated webpack / Rspack configuration?#

Modern.js provides inspect command to view the final Modern.js configuration and webpack / Rspack configuration generated by the project.

➜ npx modern inspect

Inspect config succeed, open following files to view the content:

  - Builder Config: /root/my-project/dist/rsbuild.config.mjs
  - Rspack Config (web): /root/my-project/dist/rspack.config.web.mjs

'compilation' argument error when webpack compiling?#

If the following error occurs when compiling, it is usually caused by installing the wrong version of webpack in the project, or installing multiple versions of webpack:

TypeError: The 'compilation' argument must be an instance of Compilation

The webpack version problem has the following situations:

1. The webpack dependency is directly declared in the project's package.json, and the version range of the webpack that the Modern.js depends on is different and cannot match the same version.
2. Multiple npm packages installed in the project all depend on webpack, and the webpack version ranges they depend on are different and cannot match the same version.
3. Due to the lock mechanism of the package manager, multiple webpack versions are generated in the lock file.

In the first case, it is recommended to remove the webpack dependency from the project's package.json. Because Modern.js encapsulates webpack-related capabilities by default, and will pass in the webpack object in the tools.webpack configuration option. Therefore, in most cases, it is not recommended to install additional webpack dependencies in the project.

In the second case, it is recommended to see if you can upgrade an npm package so that its dependent webpack version range is consistent with the Modern.js. It is also possible to manually unify versions through the ability of the package manager, e.g. using yarn resolutions or [pnpm overrides](https ://pnpm.io/package_json#pnpmoverrides).

If it is the third case, you can use the two methods mentioned in the second case, or you can try to delete the lock file and reinstall it to solve it.

Failed import other modules in Monorepo?#

Due to considerations of compilation performance, by default, the Modern.js does not compile files under node_modules or files outside the current project directory.

Therefore, when you reference the source code of other sub-projects, you may encounter an error similar to You may need an additional loader to handle the result of these loaders.

There are several solutions to this problem:

1. You can enable the source code build mode to compile other sub-projects within the monorepo. Please refer to Source Code Build Mode for more information.
2. You can add the source.include configuration option to specify the directories or modules that need to be additionally compiled. Please refer to Usage of source.include for more information.
3. You can pre-build the sub-projects that need to be referenced, generate the corresponding build artifacts, and then reference the build artifacts in the current project instead of referencing the source code.

Find exports is not defined runtime error?#

If the compilation is succeed, but the exports is not defined error appears after opening the page, it is usually because a CommonJS module is compiled by Babel.

Under normal circumstances, Modern.js will not use Babel to compile CommonJS modules. If the source.include configuration option is used in the project, some CommonJS modules may be added to the Babel compilation.

There are two workarounds for this problem:

1. Avoid adding CommonJS modules to Babel compilation.
2. Set Babel's sourceType configuration option to unambiguous, for example:

export default {
  tools: {
    babel(config) {
      config.sourceType = 'unambiguous';
    },
  },
};

Setting sourceType to unambiguous may have some other effects, please refer to Babel official documentation.

Compile error "Error: ES Modules may not assign module.exports or exports.*, Use ESM export syntax"?#

If the following error occurs during compilation, it is usually because a CommonJS module is compiled with Babel in the project, and the solution is same as the above exports is not defined problem.

Error: ES Modules may not assign module.exports or exports.*, Use ESM export syntax, instead: 581

For more information, please refer to issue: babel#12731.

The compilation progress bar is stuck, but there is no Error log in the terminal?#

When the compilation progress bar is stuck, but there is no Error log on the terminal, it is usually because an exception occurred during the compilation. In some cases, when Error is caught by webpack or other modules, the error log can not be output correctly. The most common scenario is that there is an exception in the Babel config, which is caught by webpack, and webpack swallows the Error in some cases.

Solution:

If this problem occurs after you modify the Babel config, it is recommended to check for the following incorrect usages:

1. You have configured a plugin or preset that does not exist, maybe the name is misspelled, or it is not installed correctly.

// wrong example
export default {
  tools: {
    babel(config, { addPlugins }) {
      // The plugin has the wrong name or is not installed
      addPlugins('babel-plugin-not-exists');
    },
  },
};

2. Whether multiple babel-plugin-imports are configured, but the name of each babel-plugin-import is not declared in the third item of the array.

// wrong example
export default {
  tools: {
    babel(config, { addPlugins }) {
      addPlugins([
        [
          'babel-plugin-import',
          { libraryName: 'antd', libraryDirectory: 'es' },
        ],
        [
          'babel-plugin-import',
          { libraryName: 'antd-mobile', libraryDirectory: 'es' },
        ],
      ]);
    },
  },
};

// correct example
export default {
  tools: {
    babel(config, { addPlugins }) {
      addPlugins([
        [
          'babel-plugin-import',
          { libraryName: 'antd', libraryDirectory: 'es' },
          'antd',
        ],
        [
          'babel-plugin-import',
          { libraryName: 'antd-mobile', libraryDirectory: 'es' },
          'antd-mobile',
        ],
      ]);
    },
  },
};

In addition to the reasons mentioned above, there is another possibility that can cause Babel compilation to hang, which is when Babel compiles a large JS file exceeding 10,000 lines (usually a large file in the node_modules directory that is compiled using source.include).

When Babel compiles large files, the built-in babel-plugin-styled-components in Modern.js can cause the compilation to hang. There is already a relevant issue in the community .

In the future, Modern.js will consider removing the built-in babel-plugin-styled-components. In the current version, you can set tools.styledComponents to false to remove this plugin.

export default {
  tools: {
    styledComponents: false,
  },
};

The webpack cache does not work?#

Modern.js enables webpack's persistent cache by default.

After the first compilation is completed, the cache file will be automatically generated and output to the ./node_modules/.cache/webpack directory. When the second compilation is performed, the cache is hit and the compilation speed is greatly improved.

When configuration files such as package.json are modified, the cache is automatically invalidated.

If the webpack compilation cache in the project has not taken effect, you can add the following configuration for troubleshooting:

export default {
  tools: {
    webpack(config) {
      config.infrastructureLogging = {
        ...config.infrastructureLogging,
        debug: /webpack\.cache/,
      };
    },
  },
};

After adding the above configuration, webpack will output logs for debugging. Please refer to the logs related to PackFileCacheStrategy to understand the cause of cache invalidation.

Compilation error after referencing a type from lodash#

If the @types/lodash package is installed in your project, you may import some types from lodash, such as the DebouncedFunc type:

import { debounce, DebouncedFunc } from 'lodash';

Modern.js will throw an error after compiling the above code:

Syntax error: /project/src/index.ts: The lodash method `DebouncedFunc` is not a known module.
Please report bugs to https://github.com/lodash/babel-plugin-lodash/issues.

The reason is that Modern.js has enabled the babel-plugin-lodash plugin by default to optimize the bundle size of lodash, but Babel cannot distinguish between "value" and "type", which resulting in an exception in the compiled code.

The solution is to use TypeScript's import type syntax to explicitly declare the DebouncedFunc type:

import { debounce } from 'lodash';
import type { DebouncedFunc } from 'lodash';