Commit 6aefb3d

title: browser.dependencySourcemaps | Config

outline: deep

- **Type:** `boolean`

- **Default:** `true`

Serve sourcemaps of your dependencies (files in `node_modules`) to the browser during headless test runs.

These sourcemaps are used by browser devtools: with `dependencySourcemaps: false`, pausing inside dependency code shows the compiled code the browser actually runs instead of the dependency's original sources. If you don't debug into your dependencies this way, disabling them makes test runs faster: the server doesn't generate and inline the maps, and every browser tab downloads several times fewer bytes.

Reported test errors are not affected: when an error is thrown inside a pre-bundled dependency, Vitest maps its stack frames using the sourcemaps stored on disk even when this option is disabled. Frames from dependencies that are served without pre-bundling (for example, [linked packages](https://vite.dev/guide/dep-pre-bundling#monorepos-and-linked-dependencies)) that don't ship their own sourcemaps fall back to the position in the served code, which usually matches the original file.

Vitest never serves sourcemaps of its own pre-built modules in headless runs (unless [`--inspect`](/guide/cli#inspect) is used) — their frames are hidden from stack traces anyway. Sourcemaps of your own source files are always served.

::: tip

If some of your workspace code resolves to a `node_modules` path (for example, with `resolve.preserveSymlinks`), set [`server.sourcemapIgnoreList`](https://vite.dev/config/server-options#server-sourcemapignorelist) to keep its sourcemaps even when this option is disabled.

:::

- **CLI:** `--browser.dependencySourcemaps`

- **Config:** [browser.dependencySourcemaps](/config/browser/dependencysourcemaps)

Serve sourcemaps of dependencies to the browser in headless runs, used by devtools when debugging into `node_modules`. Reported test errors are source-mapped either way. Use `--browser.dependencySourcemaps=false` to speed up test runs if you don't step into dependency code (default: `true`)

import { cleanUrl, toArray } from '@vitest/utils/helpers'

import { isCSSRequest, isFileServingAllowed, isValidApiRequest, rolldownVersion, distDir as vitestDist } from 'vitest/node'

{

name: 'vitest:browser:framework-sourcemaps',

enforce: 'post',

transform(code, id) {

const parentServer = contribution.parent as ParentBrowserProject | undefined

// In a headless run nothing can open devtools, so sourcemaps of

// Vitest's own pre-built modules are never consumed: their stack

// frames are filtered by stackIgnorePatterns. Generating and

// inlining these maps costs server CPU and multiplies the bytes

// the browser downloads by ~5 for every fresh browser context.

// Sourcemaps of user files and (by default) their dependencies are

// kept — they point error stacks and devtools at original sources.

if (

!parentServer

|| !isHeadlessServer(parentServer)

|| parentServer.vitest.config.inspector.enabled

) {

return null

}

if (isCSSRequest(id)) {

return null

}

const path = cleanUrl(id)

if (path.startsWith(distRoot) || path.startsWith(vitestDist)) {

return { code, map: { mappings: '' } as any }

}

// users that never debug into node_modules can drop dependency

// sourcemaps entirely; `server.sourcemapIgnoreList` (default:

// node_modules) can opt paths back in even then, e.g. with

// `preserveSymlinks` where workspace code keeps its node_modules

// path and would be wrongly treated as a dependency

if (

parentServer.config.browser.dependencySourcemaps === false

&& path.includes('/node_modules/')

&& (parentServer.vite.config.server.sourcemapIgnoreList(path, path) ?? true)

) {

return { code, map: { mappings: '' } as any }

}

return null

},

},

function isHeadlessServer(parentServer: ParentBrowserProject): boolean {

if (!parentServer.config.browser.headless) {

return false

}

// sibling instances share this server (and its module graph cache, so a

// late-spawned instance would receive already-cached transforms) and can

// override `headless` — check the static instance options instead of the

// lazily populated `children` to stay deterministic across runs

const instances = parentServer.config.browser.instances ?? []

return instances.every(instance => instance.headless !== false)

const filePath = id.split('?')[0]

// prefer the map stored on disk when the transform pipeline can't

// provide a usable one:

// - pre-bundled deps: the pipeline map resolves back into the

// optimizer cache, while the map esbuild wrote next to the file

// points at the real package sources

// - an empty `mappings` means the map was intentionally not served

// to the browser (`vitest:browser:framework-sourcemaps`), but disk

// is still the source of truth for error stack traces

if (

result && (

!result.map

|| result.map.mappings === ''

|| filePath.startsWith(this.vite.config.cacheDir)

)

) {

dependencySourcemaps: {

description: 'Serve sourcemaps of dependencies to the browser in headless runs, used by devtools when debugging into `node_modules`. Reported test errors are source-mapped either way. Use `--browser.dependencySourcemaps=false` to speed up test runs if you don\'t step into dependency code (default: `true`)',

},

/**

dependencySourcemaps?: boolean