---
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.

{% tab title="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:

```javascript
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="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
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/',
        },
      },
    }),
  ],
};
```

To also display inline source code in Error Tracking stack traces, pair service and version source map uploads with the [Source Code Context][5] plugin.
{% /tab %}

{% alert level="info" %}
These examples use 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 %}

## 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)