{"id":14054308,"url":"https://github.com/rspack-contrib/rsbuild-plugin-check-syntax","last_synced_at":"2025-04-14T10:20:37.228Z","repository":{"id":251560414,"uuid":"837770689","full_name":"rspack-contrib/rsbuild-plugin-check-syntax","owner":"rspack-contrib","description":"An Rsbuild plugin to check the syntax compatibility of output files.","archived":false,"fork":false,"pushed_at":"2025-04-01T03:26:28.000Z","size":201,"stargazers_count":10,"open_issues_count":2,"forks_count":8,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-03T08:03:16.339Z","etag":null,"topics":["rsbuild","rsbuild-plugin","rspack"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rspack-contrib.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-04T01:29:01.000Z","updated_at":"2025-04-01T03:26:31.000Z","dependencies_parsed_at":"2024-11-08T13:35:40.762Z","dependency_job_id":"596758e4-c881-454f-b802-a8ed0ba1622b","html_url":"https://github.com/rspack-contrib/rsbuild-plugin-check-syntax","commit_stats":null,"previous_names":["rspack-contrib/rsbuild-plugin-check-syntax"],"tags_count":7,"template":false,"template_full_name":"rspack-contrib/rsbuild-plugin-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rspack-contrib%2Frsbuild-plugin-check-syntax","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rspack-contrib%2Frsbuild-plugin-check-syntax/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rspack-contrib%2Frsbuild-plugin-check-syntax/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rspack-contrib%2Frsbuild-plugin-check-syntax/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rspack-contrib","download_url":"https://codeload.github.com/rspack-contrib/rsbuild-plugin-check-syntax/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248860007,"owners_count":21173342,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["rsbuild","rsbuild-plugin","rspack"],"created_at":"2024-08-12T21:01:01.025Z","updated_at":"2025-04-14T10:20:37.221Z","avatar_url":"https://github.com/rspack-contrib.png","language":"TypeScript","funding_links":[],"categories":["Plugins"],"sub_categories":["Rsbuild Plugins"],"readme":"# @rsbuild/plugin-check-syntax\n\nAn Rsbuild plugin to check the syntax compatibility of output files.\n\nThis plugin tries to find incompatible syntax in the output files with the current browserslist value. If any incompatible syntax is found, it will print detailed information to the terminal and abort the build.\n\n\u003cp\u003e\n  \u003ca href=\"https://npmjs.com/package/@rsbuild/plugin-check-syntax\"\u003e\n   \u003cimg src=\"https://img.shields.io/npm/v/@rsbuild/plugin-check-syntax?style=flat-square\u0026colorA=564341\u0026colorB=EDED91\" alt=\"npm version\" /\u003e\n  \u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square\u0026colorA=564341\u0026colorB=EDED91\" alt=\"license\" /\u003e\n  \u003ca href=\"https://npmcharts.com/compare/@rsbuild/plugin-check-syntax?minimal=true\"\u003e\u003cimg src=\"https://img.shields.io/npm/dm/@rsbuild/plugin-check-syntax.svg?style=flat-square\u0026colorA=564341\u0026colorB=EDED91\" alt=\"downloads\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n![image](https://github.com/user-attachments/assets/9a639d60-2f44-4bc4-ac27-808568fa3842)\n\n## Usage\n\nInstall:\n\n```bash\nnpm add @rsbuild/plugin-check-syntax -D\n```\n\nAdd plugin to your Rsbuild config:\n\n```ts\n// rsbuild.config.ts\nimport { pluginCheckSyntax } from \"@rsbuild/plugin-check-syntax\";\n\nexport default {\n  plugins: [pluginCheckSyntax()],\n};\n```\n\nThis plugin is compatible with both Rsbuild and Rspack. If you are using Rspack instead of Rsbuild, you can import the `CheckSyntaxRspackPlugin` from the package:\n\n```ts\n// rspack.config.mjs\nimport { defineConfig } from \"@rspack/cli\";\nimport { CheckSyntaxRspackPlugin } from \"@rsbuild/plugin-check-syntax\";\n\nexport default defineConfig({\n  mode: process.env.NODE_ENV === \"production\" ? \"production\" : \"development\",\n  devtool: \"source-map\",\n  plugins: [\n    new CheckSyntaxRspackPlugin({\n      ecmaVersion: 2015,\n    }),\n  ],\n});\n```\n\n\u003e When using `CheckSyntaxRspackPlugin`, it will not read the browserslist configuration from the project, so you need to specify the [ecmaVersion](#ecmaVersion) or [targets](#targets) option.\n\n## Enable Detection\n\nAfter registering the Check Syntax plugin, Rsbuild will perform syntax checking after production builds.\n\nWhen Rsbuild detects incompatible advanced syntax in the build artifacts, it will print the error logs in the terminal and exit the current build process.\n\n### Error Logs\n\nThe format of the error logs is as follows, including the source file, artifact location, error reason, and source code:\n\n```bash\nerror   [@rsbuild/plugin-check-syntax] Find some syntax that does not match \"ecmaVersion \u003c= 2015\":\n\n  Error 1\n  source:  /node_modules/foo/index.js:1:0\n  output:  /dist/static/js/main.3f7a4d7e.js:2:39400\n  reason:  Unexpected token (1:178)\n  code:\n     9 |\n    10 | var b = 2;\n    11 |\n  \u003e 12 | console.log(() =\u003e {\n    13 |   return a + b;\n    14 | });\n    15 |\n```\n\nCurrently, syntax checking is implemented based on AST parser. Each time it performs a check, it can only identify the first incompatible syntax found in the file. If there are multiple incompatible syntaxes in the file, you need to fix the detected syntax and re-run the check.\n\nIf the corresponding source location is not shown in the log, try setting [output.minify](/config/output/minify) to false and rebuild again.\n\nNote that displaying source code information depends on the source map file. You can configure the [output.sourceMap](/config/output/source-map) option to generate source map files during production builds.\n\n```js\nexport default {\n  output: {\n    sourceMap: {\n      js:\n        process.env.NODE_ENV === \"production\"\n          ? \"source-map\"\n          : \"cheap-module-source-map\",\n    },\n  },\n};\n```\n\n### Solutions\n\nIf a syntax error is detected, you can handle it in the following ways:\n\n- If you want to downgrade this syntax to ensure good code compatibility, you can compile the specified module through the [source.include](https://rsbuild.dev/config/source/include) config.\n- If you don't want to downgrade the syntax, you can adjust the project's [browserslist](https://rsbuild.dev/guide/advanced/browserslist) to match the syntax, or set the [ecmaVersion](#ecmaVersion) option.\n- If you don't want to check the syntax of specified files, you can use the [exclude](#exclude) option to exclude the files to be checked.\n\nTake `/node_modules/foo/index.js` as an example, you can add it to [source.include](https://rsbuild.dev/config/source/include) to compile it:\n\n```ts\n// rsbuild.config.ts\nexport default {\n  source: {\n    include: [/node_modules[\\\\/]foo[\\\\/]/],\n  },\n};\n```\n\n## Options\n\n### targets\n\n- **Type:** `string[]`\n- **Default:** `The browserslist configuration of the current project`\n\n`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.\n\nRsbuild 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.\n\n- **Example:**\n\nFor example, if the target browsers to be compatible with in the project are Chrome 53 and later versions, you can add the following configuration:\n\n```ts\npluginCheckSyntax({\n  targets: [\"chrome \u003e= 53\"],\n});\n```\n\nRsbuild will deduce that the ECMAScript syntax version that can be used with `chrome \u003e= 53` is ES2015. When the build artifacts contain `ES2016` or higher syntax, it triggers syntax error prompts.\n\n\u003e If you want to learn more about how to use browserslist, please refer to [\"Browserslist\"](https://rsbuild.dev/guide/advanced/browserslist).\n\n### ecmaVersion\n\n- **Type:** `3 | 5 | 6 | 2015 | 2016 | 2017 | 2018 | 2019 | 2020 | 2021 | 2022 | 2023 | 2024 | 2025 | 'latest'`\n- **Default:** `Automatically analyzed based on targets`\n\n`ecmaVersion` represents the minimum ECMAScript syntax version that can be used in the build artifact.\n\n\u003e If `ecmaVersion` is not set, Check Syntax plugin will infer the ECMAScript version based on `targets`. Currently, the supported inference range is `es5` ~ `es2018`.\n\n- **Example:**\n\nFor example, if the minimum ECMAScript syntax version that can be used in the build artifacts is ES2020, you can add the following configuration:\n\n```ts\npluginCheckSyntax({\n  ecmaVersion: 2020,\n});\n```\n\nAt this time, the build artifacts can include all syntax supported by ES2020, such as optional chaining.\n\n### exclude\n\n- **Type:** `RegExp | RegExp[]`\n- **Default:** `undefined`\n\n`exclude` is used to exclude a portion of source 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.\n\n- **Example:**\n\nFor example, to ignore files under the `node_modules/foo` directory:\n\n```ts\npluginCheckSyntax({\n  exclude: /node_modules\\/foo/,\n});\n```\n\n### excludeOutput\n\n- **Type:** `RegExp | RegExp[]`\n- **Default:** `undefined`\n\n`excludeOutput` is used to exclude a portion of output files before detection. You can pass in one or more regular expressions to match the paths of output files. Files that match the regular expression will be ignored and will not trigger syntax checking.\n\n- **Example:**\n\nFor example, to ignore files under the `dist/js` directory:\n\n```ts\npluginCheckSyntax({\n  excludeOutput: /dist\\/js/,\n});\n```\n\n### excludeErrorLogs\n\n- **Type:** `('source' | 'output' | 'reason' | 'code')[]`\n- **Default:** `[]`\n\n`excludeErrorLogs` is used to ignore specified syntax error messages after detection. You can pass in one or more error message types to ignore.\n\n- **Example:**\n\nFor example, to ignore the reason and code displayed in the terminal.\n\n```ts\npluginCheckSyntax({\n  excludeErrorLogs: [\"reason\", \"code\"],\n});\n```\n\n## Limitations\n\n### Syntax detection range\n\nThis plugin only checks incompatible syntax in the outputs and cannot detect missing polyfills.\n\n### Syntax detection accuracy\n\nThe syntax detection in this plugin may have some limitations due to the granularity difference between the AST parser and the actual compiler:\n\n1. **Parser Granularity**: This plugin uses [Acorn](https://github.com/acornjs/acorn) as its parser, which can only check syntax compatibility at the ECMAScript version level (like ES5, ES2015, etc).\n\n2. **Compiler Granularity**: The JavaScript compiler (such as SWC) is more fine-grained and can handle individual syntax features independently. For example, it knows that Firefox 45 supports arrow functions even though it doesn't support all ES2015 features.\n\nThis difference can lead to false positives. For example:\n\n- When your browserslist includes `firefox \u003e= 45`:\n  - SWC correctly determines that arrow functions can be used since Firefox 45 supports them\n  - This plugin will report an error because Firefox 45 doesn't support all ES2015 features\n\nTherefore, you might encounter situations where the compiled output is actually compatible with your target browsers, but this plugin still reports errors due to this granularity mismatch.\n\n#### Solutions\n\nThere are several ways to handle these false positives:\n\n1. **Manually set higher ecmaVersion**\n\nYou can manually set a higher `ecmaVersion` in the plugin configuration:\n\n```ts\npluginCheckSyntax({\n  ecmaVersion: 2016, // or higher version\n});\n```\n\nThis can immediately resolve false positive issues, but it may miss some real compatibility issues for your target browsers.\n\n2. **Use the exclude option**\n\nIf you are confident that certain files are safe, you can exclude them from checking:\n\n```ts\npluginCheckSyntax({\n  exclude: [/specific\\/file\\/path/],\n});\n```\n\n## License\n\n[MIT](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frspack-contrib%2Frsbuild-plugin-check-syntax","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frspack-contrib%2Frsbuild-plugin-check-syntax","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frspack-contrib%2Frsbuild-plugin-check-syntax/lists"}