Source Maps

Overview

The Source Maps build plugin automatically uploads JavaScript source maps to Datadog during your build, enabling deobfuscated stack traces in Error Tracking and RUM. 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.

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 for bundler-specific source map generation setup.
  • The RUM SDK initialized with service and version parameters that match the plugin’s service and releaseVersion configuration.
  • The Datadog build plugin installed and registered with your bundler. See Build Plugins for installation instructions.

Configuration

Configure the errorTracking.sourcemaps object in your build plugin options:

ParameterTypeRequiredDefaultDescription
errorTracking.sourcemaps.serviceStringYesNoneService name. Must match the RUM SDK service initialization parameter.
errorTracking.sourcemaps.releaseVersionStringYesNoneRelease version. Must match the RUM SDK version initialization parameter.
errorTracking.sourcemaps.minifiedPathPrefixStringYesNoneURL or root-relative path prefix for your minified JavaScript files are served. For example, https://example.com/static/ or /static/.
errorTracking.sourcemaps.bailOnErrorBooleanNofalseIf true, the build fails when a source map upload error occurs.
errorTracking.sourcemaps.dryRunBooleanNofalseIf true, the plugin runs through the upload process without sending data to Datadog. Use this to verify your configuration.
errorTracking.sourcemaps.maxConcurrencyNumberNo20Maximum number of concurrent source map uploads.

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.

Example

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/',
        },
      },
    }),
  ],
};
This example uses webpack. The configuration object is identical across all supported bundlers — only the import and plugin function name differ. See Build Plugins for installation instructions for your bundler.

To also display inline source code in Error Tracking stack traces, pair source map uploads with the Source Code Context plugin. Source maps provide the file mapping; source code context provides the service and version association.

Further reading

Additional helpful documentation, links, and articles:

Upload JavaScript Source Maps (manual method)DOCUMENTATION more more Error TrackingDOCUMENTATION more more Datadog Build Plugins GitHub RepositorySOURCE CODE more more