import WebpackLicense from '@components/WebpackLicense';

Devtool

The devtool option controls the debugging information Rspack generates for output code, including whether source maps are generated, how they are emitted, and their mapping precision. The selected value affects how well browser development tools and error monitoring services can map bundled code back to the original source. It also affects build speed and the risk of exposing source code.

• Type:

type Devtool = string | false;

• Default: cheap-module-source-map in development mode and false in production mode

Recommended configurations

The following examples use process.env.NODE_ENV to distinguish development from production.

Development only

If you only need debugging information during development and do not need source maps in production, use the following configuration:

const isDev = process.env.NODE_ENV === 'development';

export default {
  devtool: isDev ? 'cheap-module-source-map' : false,
};

• Development: Uses cheap-module-source-map to generate line-level source maps, balancing debugging accuracy and build speed.
• Production: Sets devtool to false, so no source maps are emitted and no source map generation overhead is added.

Disabled everywhere

If neither environment needs source maps, use the following configuration:

export default {
  devtool: false,
};

This configuration has the lowest build overhead and does not emit .map files. The tradeoff is that browser errors and production stack traces can only point to bundled code and cannot be mapped back to the original source.

Enabled everywhere

If you want fast source maps during development and complete line and column mappings in production, use the following configuration:

const isDev = process.env.NODE_ENV === 'development';

export default {
  devtool: isDev ? 'cheap-module-source-map' : 'source-map',
};

• Development: Uses the faster cheap-module-source-map.
• Production: Uses source-map, which emits a separate .map file with line and column mappings and adds a sourceMappingURL comment to the bundle. As long as the .map file is accessible, browser development tools can load it automatically. This is useful for debugging production code directly, but it increases build time and may expose your source code to users.

Hidden production reference

If you need production source maps to reconstruct error stack traces but do not want browsers to discover them automatically from the bundle, use the following configuration:

const isDev = process.env.NODE_ENV === 'development';

export default {
  devtool: isDev ? 'cheap-module-source-map' : 'hidden-source-map',
};

• Development: Uses the faster cheap-module-source-map.
• Production: Uses hidden-source-map, which emits a separate .map file with complete line and column mappings but does not add a //# sourceMappingURL comment to the bundle. This is useful when uploading source maps privately to an error monitoring service to reconstruct production stack traces.

:::warning hidden-source-map only removes the reference from the bundle; it does not encrypt or protect the .map file. Unless you explicitly intend to publish your source code, do not deploy production .map files to a publicly accessible web server or CDN. Upload them to an access-controlled error monitoring service instead. :::

Common values

The following table compares the mapping precision, output format, and typical use of common values.

Modifiers

Without modifiers, source-map emits a separate .map file with line and column mappings and adds a sourceMappingURL comment to the bundle. Add the following modifiers to change how the map is emitted, its mapping precision, or its contents.

eval

Wraps each module in eval(). When combined with source-map as eval-source-map, each module's source map is written to its eval() as a Data URL. This avoids combining source maps at the chunk level and improves rebuild performance. This modifier is normally used only in development.

Using devtool: 'eval' by itself does not generate a source map. Instead, a //# sourceURL comment gives each module a readable name. This identifies the module but cannot map generated code back to the original source.

inline

Embeds the source map in the bundle as a Data URL instead of emitting a separate .map file, as in inline-source-map. This is convenient when distributing a single file, but it significantly increases bundle size. By default, the source map also includes source content in the bundle; combining it with nosources omits that content. This modifier is therefore normally limited to development or testing.

hidden

Emits a separate .map file without adding a //# sourceMappingURL comment to the bundle, as in hidden-source-map. Browsers do not discover the file automatically, making it suitable for private uploads to error monitoring services. It does not prevent users from accessing a publicly deployed .map file directly.

nosources

Removes sourcesContent from the source map, as in nosources-source-map. The map still contains original filenames, directory structure, and mapping information, so it can reconstruct stack traces, but it cannot provide the original source content to development tools on its own.

cheap

Generates line mappings only, omitting column mappings to reduce source map computation, as in cheap-source-map. On its own, it ignores source maps provided by loaders, so mappings point to loader-transformed code rather than the original source.

:::tip In production builds with minification enabled, no source map file may be emitted when using the cheap modifier, such as cheap-source-map or cheap-module-source-map. This is expected: minified code typically occupies a single line, while cheap provides line-level mappings only. A .map file may still be emitted when minification is disabled. :::

module

Used only together with cheap, as in cheap-module-source-map. It processes source maps provided by loaders so line mappings point back to the original source. Compared with cheap-source-map, it produces more accurate mappings at a slightly higher computation cost. Without cheap, source-map already processes loader source maps, so module is unnecessary.

debugids

The debugids modifier adds a debugId to the source map following the TC39 Debug ID proposal. For example, with source-map-debugids, Rspack also adds a matching //# debugId comment to the corresponding output asset so error monitoring tools can associate the build artifact with its source map.

Rspack validates modifier order. Values must match [inline-|hidden-|eval-][nosources-][cheap-[module-]]source-map[-debugids]. The inline, hidden, and eval modifiers are mutually exclusive, module can only follow cheap, and debugids must appear at the end.

Related options

• output.sourceMapFilename customizes the name of separate source map files.
• output.devtoolModuleFilenameTemplate, output.devtoolFallbackModuleFilenameTemplate, and output.devtoolNamespace control module names in source maps and avoid naming conflicts across builds.
• rules[].extractSourceMap extracts an existing source map from an input file's sourceMappingURL comment.

Fine-grained control

For finer-grained control over source map generation, set devtool to false and use SourceMapDevToolPlugin instead. For eval-based source maps, use EvalSourceMapDevToolPlugin instead.