---
title: Source Maps
description: >-
  Automatically upload JavaScript source maps to Datadog at build time to
  deobfuscate stack traces in Error Tracking and RUM.
breadcrumbs: >-
  Docs > RUM & Session Replay > Application Monitoring > RUM Browser Monitoring
  > Build Plugins > Source Maps
---

> For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt).

# Source Maps

## Overview{% #overview %}

The Source Maps build plugin automatically uploads JavaScript source maps to Datadog during your build, enabling deobfuscated stack traces in [Error Tracking](https://docs.datadoghq.com/real_user_monitoring/error_tracking.md) and [RUM](https://docs.datadoghq.com/real_user_monitoring.md). This replaces the need to manually run `datadog-ci sourcemaps upload` or configure CI/CD pipelines for source map uploads.

The plugin hooks into the build process, discovers all `.js` files with corresponding `.map` source map files from the build output, and uploads them to Datadog with git metadata. It can associate source maps with events by debug ID or by service and version.

## Prerequisites{% #prerequisites %}

- A Datadog API key, set with `auth.apiKey` or the `DATADOG_API_KEY` environment variable.
- Source maps enabled in your bundler configuration. The plugin uploads source maps but does not generate them. See [Upload JavaScript Source Maps](https://docs.datadoghq.com/real_user_monitoring/guide/upload-javascript-source-maps.md#instrument-your-code) for bundler-specific source map generation setup.
- For debug ID uploads, enable debug ID injection in the build plugin.
- For service and version uploads, initialize the RUM SDK with `service` and `version` parameters that match the plugin configuration.
- The Datadog build plugin installed and registered with your bundler. See [Build Plugins](https://docs.datadoghq.com/real_user_monitoring/application_monitoring/browser/build_plugins.md) for installation instructions.

## Configuration{% #configuration %}

The following environment variables override configuration values:

- `DATADOG_SITE` or `DD_SITE`: Overrides `auth.site` for the intake URL.
- `DATADOG_SOURCEMAP_INTAKE_URL`: Overrides the full intake URL directly.

Choose one source map upload matching method: debug ID or service and version. These upload methods are mutually exclusive.

### Debug ID (recommended){% #debug-id-recommended %}

Debug IDs associate each JavaScript bundle with its source map without relying on the bundle URL, service, or version. Use this method for new configurations.

Debug ID support requires [Datadog Build Plugins version 3.3.0](https://github.com/DataDog/build-plugins/releases/tag/v3.3.0) or later.

Configure the following options in `sourcemaps`:

| Parameter        | Type    | Required       | Default | Description                                                                                                                   |
| ---------------- | ------- | -------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `debugId`        | Boolean | Yes            | None    | Set to `true` to inject a debug ID into each JavaScript bundle.                                                               |
| `upload`         | Boolean | Yes, to upload | `false` | Set to `true` to upload source maps during the build. If omitted, the plugin only injects debug IDs.                          |
| `bailOnError`    | Boolean | No             | `false` | If `true`, the build fails when a source map upload error occurs.                                                             |
| `dryRun`         | Boolean | No             | `false` | If `true`, the plugin runs through the upload process without sending data to Datadog. Use this to verify your configuration. |
| `maxConcurrency` | Number  | No             | `20`    | Maximum number of concurrent source map uploads.                                                                              |

Set `debugId` and `upload` to `true` to inject debug IDs and upload source maps during the build:

{% tab title="Webpack" %}

```javascript
// webpack.config.js
const { datadogWebpackPlugin } = require('@datadog/webpack-plugin');

module.exports = {
  plugins: [
    datadogWebpackPlugin({
      auth: {
        apiKey: process.env.DATADOG_API_KEY,
        site: 'datadoghq.com', // Optional: defaults to datadoghq.com
      },
      sourcemaps: {
        debugId: true,
        upload: true,
      },
    }),
  ],
};
```

{% /tab %}

{% tab title="Vite" %}

```javascript
// vite.config.js
import { datadogVitePlugin } from '@datadog/vite-plugin';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    datadogVitePlugin({
      auth: {
        apiKey: process.env.DATADOG_API_KEY,
        site: 'datadoghq.com', // Optional: defaults to datadoghq.com
      },
      sourcemaps: {
        debugId: true,
        upload: true,
      },
    }),
  ],
});
```

{% /tab %}

{% tab title="esbuild" %}

```javascript
// esbuild.config.js
const { datadogEsbuildPlugin } = require('@datadog/esbuild-plugin');

require('esbuild').build({
  plugins: [
    datadogEsbuildPlugin({
      auth: {
        apiKey: process.env.DATADOG_API_KEY,
        site: 'datadoghq.com', // Optional: defaults to datadoghq.com
      },
      sourcemaps: {
        debugId: true,
        upload: true,
      },
    }),
  ],
});
```

{% /tab %}

{% tab title="Rollup" %}

```javascript
// rollup.config.js
import { datadogRollupPlugin } from '@datadog/rollup-plugin';

export default {
  plugins: [
    datadogRollupPlugin({
      auth: {
        apiKey: process.env.DATADOG_API_KEY,
        site: 'datadoghq.com', // Optional: defaults to datadoghq.com
      },
      sourcemaps: {
        debugId: true,
        upload: true,
      },
    }),
  ],
};
```

{% /tab %}

{% tab title="Rspack" %}

```javascript
// rspack.config.js
const { datadogRspackPlugin } = require('@datadog/rspack-plugin');

module.exports = {
  plugins: [
    datadogRspackPlugin({
      auth: {
        apiKey: process.env.DATADOG_API_KEY,
        site: 'datadoghq.com', // Optional: defaults to datadoghq.com
      },
      sourcemaps: {
        debugId: true,
        upload: true,
      },
    }),
  ],
};
```

{% /tab %}

### Service and version{% #service-and-version %}

Configure the `errorTracking.sourcemaps` object to upload source maps using service and version matching:

| Parameter            | Type    | Required                              | Default | Description                                                                                                                                 |
| -------------------- | ------- | ------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `service`            | String  | Yes                                   | None    | Service name. Must match the RUM SDK `service` initialization parameter.                                                                    |
| `releaseVersion`     | String  | Yes, unless `metadata.version` is set | None    | Release version. Must match the RUM SDK `version` initialization parameter.                                                                 |
| `minifiedPathPrefix` | String  | Yes                                   | None    | URL or root-relative path prefix where your minified JavaScript files are served. For example, `https://example.com/static/` or `/static/`. |
| `bailOnError`        | Boolean | No                                    | `false` | If `true`, the build fails when a source map upload error occurs.                                                                           |
| `dryRun`             | Boolean | No                                    | `false` | If `true`, the plugin runs through the upload process without sending data to Datadog. Use this to verify your configuration.               |
| `maxConcurrency`     | Number  | No                                    | `20`    | Maximum number of concurrent source map uploads.                                                                                            |

```javascript
// webpack.config.js
const { datadogWebpackPlugin } = require('@datadog/webpack-plugin');

module.exports = {
  plugins: [
    datadogWebpackPlugin({
      auth: {
        apiKey: process.env.DATADOG_API_KEY,
        site: 'datadoghq.com', // Optional: defaults to datadoghq.com
      },
      errorTracking: {
        sourcemaps: {
          service: 'my-application',
          releaseVersion: '1.0.0',
          minifiedPathPrefix: 'https://example.com/static/',
        },
      },
    }),
  ],
};
```

{% alert level="info" %}
This example uses webpack. The configuration object is identical across all supported bundlers, only the import and plugin function name differ. See [Build Plugins](https://docs.datadoghq.com/real_user_monitoring/application_monitoring/browser/build_plugins.md) for installation instructions for your bundler.
{% /alert %}

To also display inline source code in Error Tracking stack traces, pair service and version source map uploads with the [Source Code Context](https://docs.datadoghq.com/real_user_monitoring/application_monitoring/browser/build_plugins/source_code_context.md) plugin.

## Further reading{% #further-reading %}

Additional helpful documentation, links, and articles:

- [Upload JavaScript Source Maps (manual method)](https://docs.datadoghq.com/real_user_monitoring/guide/upload-javascript-source-maps.md)
- [Error Tracking](https://docs.datadoghq.com/real_user_monitoring/error_tracking.md)
- [Datadog Build Plugins GitHub Repository](https://github.com/DataDog/build-plugins)