#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

#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',
        ],
      ]);
    },
  },
};

#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';