You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
An Rsbuild plugin to check the syntax compatibility of output files.
4
4
5
+
This 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.
After registering the Check Syntax plugin, Rsbuild will perform syntax checking after production builds.
36
+
37
+
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.
32
38
33
-
### foo
39
+
### Error Logs
34
40
35
-
Some description.
41
+
The format of the error logs is as follows, including the source file, artifact location, error reason, and source code:
36
42
37
-
- Type: `string`
38
-
- Default: `undefined`
39
-
- Example:
43
+
```bash
44
+
error [Syntax Checker] Find some syntax that does not match "ecmaVersion <= 2015":
45
+
46
+
Error 1
47
+
source: /node_modules/foo/index.js:1:0
48
+
output: /dist/static/js/main.3f7a4d7e.js:2:39400
49
+
reason: Unexpected token (1:178)
50
+
code:
51
+
9 |
52
+
10 | var b = 2;
53
+
11 |
54
+
> 12 |console.log(() => {
55
+
13 |return a + b;
56
+
14 | });
57
+
15 |
58
+
```
59
+
60
+
Currently, 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.
61
+
62
+
If the corresponding source location is not shown in the log, try setting [output.minify](/config/output/minify) to false and rebuild again.
63
+
64
+
Note 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.
40
65
41
66
```js
42
-
pluginExample({
43
-
foo:"bar",
67
+
export default {
68
+
output: {
69
+
sourceMap: {
70
+
js:
71
+
process.env.NODE_ENV === "production"
72
+
?"source-map"
73
+
:"cheap-module-source-map",
74
+
},
75
+
},
76
+
};
77
+
```
78
+
79
+
### Solutions
80
+
81
+
If a syntax error is detected, you can handle it in the following ways:
82
+
83
+
- If you want to downgrade this syntax to ensure good code compatibility, you can compile the corresponding module through the `source.include` config.
84
+
- If you don't want to downgrade the syntax, you can adjust the project's browserslist to match the syntax.
85
+
- If you do not want to check the syntax of specific files, you can use the `checkSyntax.exclude` configuration to exclude the files to be checked.
86
+
87
+
## Options
88
+
89
+
### targets
90
+
91
+
- **Type:**`string[]`
92
+
- **Default:**`The browserslist configuration of the current project`
93
+
94
+
`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.
95
+
96
+
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.
97
+
98
+
- **Example:**
99
+
100
+
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:
101
+
102
+
```ts
103
+
pluginCheckSyntax({
104
+
targets: ["chrome >= 53"],
105
+
});
106
+
```
107
+
108
+
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.
109
+
110
+
> If you want to learn more about how to use browserslist, please refer to ["Browserslist"](https://rsbuild.dev/guide/advanced/browserslist).
- **Default:**`Automatically analyzed based on targets`
116
+
117
+
`ecmaVersion` represents the minimum ECMAScript syntax version that can be used in the build artifact.
118
+
119
+
> If `ecmaVersion` is not set, Check Syntax plugin will infer the ECMAScript version based on `targets`. Currently, the supported inference range is `es5`~`es2018`.
120
+
121
+
- **Example:**
122
+
123
+
For example, if the minimum ECMAScript syntax version that can be used in the build artifacts is ES2020, you can add the following configuration:
124
+
125
+
```ts
126
+
pluginCheckSyntax({
127
+
ecmaVersion: 2020,
44
128
});
45
129
```
46
130
131
+
At this time, the build artifacts can include all syntax supported by ES2020, such as optional chaining.
132
+
133
+
### exclude
134
+
135
+
- **Type:**`RegExp | RegExp[]`
136
+
- **Default:**`undefined`
137
+
138
+
`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.
139
+
140
+
- **Example:**
141
+
142
+
For example, to ignore files under the `node_modules/foo` directory:
143
+
144
+
```ts
145
+
pluginCheckSyntax({
146
+
exclude: /node_modules\/foo/,
147
+
});
148
+
```
149
+
150
+
## Limitations
151
+
152
+
1. Check Syntax plugin only checks incompatible syntax in the outputs and cannot detect missing polyfills.
153
+
2. Check Syntax plugin's detection may be inaccurate in certain cases due to the limitations of AST parser. Check Syntax is implemented based on [Acorn](https://github.com/acornjs/acorn), which targets a specific ECMA version, such as ES2018. On the other hand, SWC can target specific syntax during compilation, such as ES2018's Object Spread. This difference means that using the same browserslist configuration, SWC's compiled output is correct, but Check Syntax may still fail detection.
0 commit comments