Check Syntax Plugin#

Check Syntax plugin is used to analyze whether there is incompatible advanced syntax in the build artifacts under the current browser scope. If any incompatible syntax is found, detailed information will be printed to the terminal.

Quick Start#

Install Plugin#

You can install the plugin using the following command:

npm add @rsbuild/plugin-check-syntax -D

Register Plugin#

You can register the plugin in the rsbuild.config.ts file:

import { pluginCheckSyntax } from '@rsbuild/plugin-check-syntax';

export default {
  plugins: [pluginCheckSyntax()],
};

Enable Detection#

After registering the Check Syntax plugin, Rsbuild will perform syntax checking after production builds.

When Rsbuild detects incompatible advanced syntax in the build artifacts, it will print the error logs in the terminal and exit the current build process.

Error Logs#

The format of the error logs is as follows, including the source file, artifact location, error reason, and source code:

error   [Syntax Checker] Find some syntax that does not match "ecmaVersion <= 2015":

  Error 1
  source:  /node_modules/foo/index.js:1:0
  output:  /dist/static/js/main.3f7a4d7e.js:2:39400
  reason:  Unexpected token (1:178)
  code:
     9 |
    10 | var b = 2;
    11 |
  > 12 | console.log(() => {
    13 |   return a + b;
    14 | });
    15 |

Note that displaying source code information depends on the source map file. You can configure the output.sourceMap option to generate source map files during production builds.

export default {
  output: {
    sourceMap: {
      js:
        process.env.NODE_ENV === 'production'
          ? 'source-map'
          : 'cheap-module-source-map',
    },
  },
};

Solutions#

If a syntax error is detected, you can handle it in the following ways:

• If you want to downgrade this syntax to ensure good code compatibility, you can compile the corresponding module through the source.include config.
• If you don't want to downgrade the syntax, you can adjust the project's browserslist to match the syntax.
• If you do not want to check the syntax of certain products, you can use the checkSyntax.exclude configuration to exclude the files to be checked.

Options#

targets#

• Type: string[]
• Default: The browserslist configuration of the current project

targets is the target browser range, its value is a standard browserslist. Check Syntax plugin will by default read the current project's browserslist configuration, so you usually don't need to manually configure the targets option.

Rsbuild will read the value of targets and automatically deduce the minimum ECMAScript syntax version that can be used in the build artifacts, such as ES5 or ES2015.

• Example:

For example, if the target browsers to be compatible with in the project are Chrome 53 and later versions, you can add the following configuration:

pluginCheckSyntax({
  targets: ['chrome >= 53'],
});

Rsbuild will deduce that the ECMAScript syntax version that can be used with chrome >= 53 is ES2015. When the build artifacts contain ES2016 or higher syntax, it triggers syntax error prompts.

ecmaVersion#

• Type: 3 | 5 | 6 | 2015 | 2016 | 2017 | 2018 | 2019 | 2020 | 2021 | 2022 | 'latest'
• Default: Automatically analyzed based on targets

ecmaVersion represents the minimum ECMAScript syntax version that can be used in the build artifact.

• Example:

For example, if the minimum ECMAScript syntax version that can be used in the build artifacts is ES2020, you can add the following configuration:

pluginCheckSyntax({
  ecmaVersion: 2020,
});

At this time, the build artifacts can include all syntax supported by ES2020, such as optional chaining.

exclude#

• Type: RegExp | RegExp[]
• Default: undefined

exclude is used to exclude a portion of files during detection. You can pass in one or more regular expressions to match the paths of source files. Files that match the regular expression will be ignored and will not trigger syntax checking.

• Example:

For example, to ignore files under the node_modules/foo directory:

pluginCheckSyntax({
  exclude: /node_modules\/foo/,
});