docs: improve devtool docs #9832
Conversation
github-actions
bot
added
release: document
✅ Deploy Preview for rspack ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
SyMind
force-pushed
the
improve-devtool-docs
branch
from
c3e44dd to
96576a4
Compare
| | 'eval-nosources-cheap-source-map' | ||
| | 'eval-nosources-cheap-module-source-map' | ||
| | 'eval-nosources-source-map'; | ||
| type Devtool = 'string' | false; | ||
| ``` | ||
|
|
||
| - **Default:** `eval` |
There was a problem hiding this comment.
This default value is not correct. Can we clarify the default value in different mode? And Rspack CLI also has a different default value.
| @@ -4,54 +4,85 @@ import WebpackLicense from '@components/WebpackLicense'; | |||
|
|
|||
| # Devtool | |||
|
|
|||
| 调试：该选项用于控制 Source Map 的生成行为。 | |||
| 该选项用于控制调试信息生成策略，影响调试能力与构建性能。 | |||
There was a problem hiding this comment.
How about "控制 source map 和调试信息的生成"
|
|
||
| - **不需要** → 设置 `devtool: false` | ||
| - 禁用所有调试信息 | ||
| - 零额外构建开销，极致构建速度 |
There was a problem hiding this comment.
This wording is more like that in a promotional article than in an official configuration document.
| | nosources | SourceMap is created without the `sourcesContent` in it | | ||
| | debugids | SourceMap is created with the `debugId` in it | | ||
|
|
||
| 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]`. |
There was a problem hiding this comment.
[inline-|hidden-|eval-][nosources-][cheap-[module-]]source-map[-debugids] is too complex for most users
|
|
||
| ### Step 2: Define Debugging Requirements | ||
|
|
||
| - **Module-level positioning only** → Set `devtool: 'eval'` |
There was a problem hiding this comment.
I feel that eval is no longer a recommended value. None of the frameworks based on webpack/Rspack use eval by default, and the code readability is quite poor.
There was a problem hiding this comment.
Even if we want to use eval, we should not use "devtool: 'eval'". We should write it like process.env.NODE_ENV === 'production' ? 'source-map' : 'eval'
|
|
||
| It also supports combination with the following modifiers to improve performance and control SourceMap generation. | ||
|
|
||
| Performance optimization modifiers, to speed up the build, usually used in development environments: |
There was a problem hiding this comment.
The modifier part is more specific, I suggest putting it after "Recommended configurations"
There was a problem hiding this comment.
Perhaps the "Configuration guide" and "Recommended configuration" sections should be combined together. Looking at the "Configuration guide" alone does not seem to be of practical reference.
Summary
Checklist