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
Copy file name to clipboardExpand all lines: website/docs/en/config/devtool.mdx
+75-36Lines changed: 75 additions & 36 deletions
Original file line number
Diff line number
Diff line change
@@ -4,54 +4,93 @@ import WebpackLicense from '@components/WebpackLicense';
4
4
5
5
# Devtool
6
6
7
-
The `devtool` configuration is used to control the behavior of the Source Map generation.
7
+
Choose a style of source mapping to enhance the debugging process. These values can affect build and rebuild speed dramatically.
8
+
9
+
Use the [SourceMapDevToolPlugin](/plugins/webpack/source-map-dev-tool-plugin) or [EvalSourceMapDevToolPlugin](/plugins/webpack/eval-source-map-dev-tool-plugin) for a more fine grained configuration.
8
10
9
11
-**Type:**
10
12
11
13
```ts
12
-
typeDevtool=
13
-
|false
14
-
|'eval'
15
-
|'cheap-source-map'
16
-
|'cheap-module-source-map'
17
-
|'source-map'
18
-
|'inline-cheap-source-map'
19
-
|'inline-cheap-module-source-map'
20
-
|'inline-source-map'
21
-
|'inline-nosources-cheap-source-map'
22
-
|'inline-nosources-cheap-module-source-map'
23
-
|'inline-nosources-source-map'
24
-
|'nosources-cheap-source-map'
25
-
|'nosources-cheap-module-source-map'
26
-
|'nosources-source-map'
27
-
|'hidden-nosources-cheap-source-map'
28
-
|'hidden-nosources-cheap-module-source-map'
29
-
|'hidden-nosources-source-map'
30
-
|'hidden-cheap-source-map'
31
-
|'hidden-cheap-module-source-map'
32
-
|'hidden-source-map'
33
-
|'eval-cheap-source-map'
34
-
|'eval-cheap-module-source-map'
35
-
|'eval-source-map'
36
-
|'eval-nosources-cheap-source-map'
37
-
|'eval-nosources-cheap-module-source-map'
38
-
|'eval-nosources-source-map';
14
+
typeDevtool='string'|false;
39
15
```
40
16
41
17
-**Default:**`eval`
42
18
43
-
The main types of Source Map generated behaviors are `source-map`, `eval`, `cheap`, `module`, `inline`, `nosources` and `hidden`, and they can be combined.
19
+
## Configuration Guide
20
+
21
+
### Step 1: Determine Debugging Needs
22
+
23
+
-**Not required** → Set `devtool: false`
24
+
- Disables all debugging information
25
+
- Zero build overhead with maximum build speed
26
+
-**Required** → Proceed to [Step 2](#step-2-define-debugging-requirements)
27
+
28
+
### Step 2: Define Debugging Requirements
29
+
30
+
-**Module-level positioning only** → Set `devtool: 'eval'`
31
+
- Each module executed via `eval()` with `//# sourceURL` comment
32
+
- Extremely fast build speed
33
+
-**Full source code mapping needed** → Proceed to [Step 3](#step-3-configure-sourcemap)
34
+
35
+
### Step 3: Configure SourceMap
36
+
37
+
Set `devtool: 'source-map'`, A full SourceMap is emitted as a separate file. It adds a `//# sourceMapURL` comment to the bundle so development tools know where to find it.
38
+
39
+
It also supports combination with the following modifiers to improve performance and control SourceMap generation.
40
+
41
+
Performance optimization modifiers, to speed up the build, usually used in development environments:
| eval | Each module is executed with `eval()` and a SourceMap is added as a DataUrl to the `eval()`, avoiding chunk-level multiple SourceMap concate | ⚡⚡⚡ |
46
+
| cheap | Maps line numbers only (no columns), ignores source maps from loaders | ⚡⚡ |
47
+
| module | Processes source maps from loaders to map to original code (line-only mapping) | ⚡ |
48
+
49
+
Functional modifiers, to control SourceMap generation, usually used in production environments:
| hidden | SourceMap is emitted as a separate file, but no `//# sourceMappingURL=[url]` comment is added to the bundle, protecting source code privacy |
54
+
| inline | SourceMap is added as a DataUrl to the bundle |
55
+
| nosources | SourceMap is created without the `sourcesContent` in it |
56
+
| debugids | SourceMap is created with the `debugId` in it |
57
+
58
+
We expect a certain pattern when validate devtool name, pay attention and don't mix up the sequence of devtool string. The pattern is: `[inline-|hidden-|eval-][nosources-][cheap-[module-]]source-map[-debugids]`.
59
+
60
+
## Recommended configurations
61
+
62
+
### Development
63
+
64
+
The following options are ideal for development:
65
+
66
+
`eval` - Each module is executed with `eval()` and `//# sourceURL`. This is pretty fast. The main disadvantage is that it doesn't display line numbers correctly since it gets mapped to transpiled code instead of the original code (No Source Maps from Loaders).
67
+
68
+
`eval-source-map` - Each module is executed with `eval()` and a SourceMap is added as a DataUrl to the `eval()`. Initially it is slow, but it provides fast rebuild speed and yields real files. Line numbers are correctly mapped since it gets mapped to the original code. It yields the best quality SourceMaps for development.
69
+
70
+
`eval-cheap-source-map` - Similar to `eval-source-map`, each module is executed with `eval()`. It is "cheap" because it doesn't have column mappings, it only maps line numbers. It ignores SourceMaps from Loaders and only display transpiled code similar to the eval devtool.
71
+
72
+
`eval-cheap-module-source-map` - Similar to `eval-cheap-source-map`, however, in this case Source Maps from Loaders are processed for better results. However Loader Source Maps are simplified to a single mapping per line.
73
+
74
+
### Production
75
+
76
+
These options are typically used in production:
44
77
45
-
-`source-map` is the most basic behavior, indicating the generation of Source Map, which has a partial overhead on build performance when Source Map is turned on.
78
+
'false' - No SourceMap is emitted. This is a good option to start with.
46
79
47
-
-`eval` wraps the module generated code with `eval()`, so Rspack can internally cache the module generated results, so when `eval` is used in combination with `source-map`, it optimizes the speed of Source Map generation when rebuilding.
80
+
`source-map` - A full SourceMap is emitted as a separate file. It adds a reference comment to the bundle so development tools know where to find it.
48
81
49
-
-`cheap` means that the Source Map will only generate the mapping of rows, ignoring the mapping of columns, in order to speed up the generation of the Source Map.
82
+
:::warning
83
+
You should configure your server to disallow access to the Source Map file for normal users!
84
+
:::
50
85
51
-
-`module` is used to control whether the loader needs to return the Source Map, so without `module`, the Source Map can only map code that will be processed by the loader, and because the loader does not need to process the Source Map, the Source Map generation speed will be improved.
86
+
`hidden-source-map` - Same as `source-map`, but doesn't add a reference comment to the bundle. Useful if you only want SourceMaps to map error stack traces from error reports, but don't want to expose your SourceMap for the browser development tools.
52
87
53
-
-`inline` indicates whether the generated Source Map is inlined into the end of the file via the data url.
88
+
:::warning
89
+
You should not deploy the Source Map file to the webserver. Instead only use it for error report tooling.
90
+
:::
54
91
55
-
-`nosources` is used to control whether the generated Source Map contains source code content to reduce the size of the generated Source Map.
92
+
`nosources-source-map` - A SourceMap is created without the `sourcesContent` in it. It can be used to map stack traces on the client without exposing all of the source code. You can deploy the Source Map file to the webserver.
56
93
57
-
-`hidden` is used to control whether the end of the generated file contains the `# sourceMappingURL=...` annotation. The browser developer tools and VS Code etc. will look for the Source Map by the path or data url of this annotation in order to map the product's row number back to its location in the source code during debugging.
94
+
:::warning
95
+
It still exposes original filenames and structure, but it doesn't expose the original code.
0 commit comments