--- title: Upload JavaScript Source Maps description: >- Upload JavaScript source maps to enhance error tracking with readable stack traces and better debugging for minified code. breadcrumbs: >- Docs > RUM & Session Replay > Real User Monitoring & Session Replay Guides > Upload JavaScript Source Maps --- > For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt). # Upload JavaScript Source Maps ## Overview{% #overview %} If your front-end JavaScript source code is minified, upload your source maps to Datadog to de-obfuscate your different stack traces. For any given error, you can access the file path, line number, and code snippet for each frame of the related stack trace. Datadog can also link stack frames to your source code in your repository. {% alert level="info" %} - Only errors collected by [Error Tracking](https://docs.datadoghq.com/error_tracking.md), [Real User Monitoring (RUM)](https://docs.datadoghq.com/real_user_monitoring.md), and logs from [Browser Logs Collection](https://docs.datadoghq.com/logs/log_collection/javascript.md) can be unminified. - To automate source map uploads as part of your build process, see [Build Plugins: Source Maps](https://docs.datadoghq.com/real_user_monitoring/application_monitoring/browser/build_plugins/source_maps.md). {% /alert %} ## Instrument your code{% #instrument-your-code %} Configure your JavaScript bundler such that when minifying your source code, it generates source maps that directly include the related source code in the `sourcesContent` attribute. {% alert level="danger" %} Ensure that the size of each source map augmented with the size of the related minified file does not exceed the limit of 500 MB. {% /alert %} See the following configurations for popular JavaScript bundlers. {% tab title="WebpackJS" %} You can generate source maps by using the built-in webpack plugin named [SourceMapDevToolPlugin](https://webpack.js.org/plugins/source-map-dev-tool-plugin/). See the example configuration in your `webpack.config.js` file: ```javascript // ... const webpack = require('webpack'); module.exports = { mode: 'production', devtool: false, plugins: [ new webpack.SourceMapDevToolPlugin({ noSources: false, filename: '[file].map' }), // ... ], optimization: { minimize: true, // ... }, // ... }; ``` **Note**: If you are using TypeScript, set `compilerOptions.sourceMap` to `true` in your `tsconfig.json` file. {% /tab %} {% tab title="ParcelJS" %} Parcel generates source maps by default when you run the build command: `parcel build `. {% /tab %} {% tab title="Vite" %} You can generate source maps by configuring the `build.sourcemap` option in your `vite.config.js` file. See the example configuration: ```javascript // vite.config.js import { defineConfig } from 'vite' export default defineConfig({ build: { sourcemap: true, // generates .js.map files minify: 'terser', // or 'esbuild' } }) ``` **Note**: If you are using TypeScript, ensure `compilerOptions.sourceMap` is set to `true` in your `tsconfig.json` file. {% /tab %} After building your application, bundlers generate a directory (typically named `dist`) with minified JavaScript files co-located with their corresponding source maps. See the following example: ```bash ./dist javascript.364758.min.js javascript.364758.js.map ./subdirectory javascript.464388.min.js javascript.464388.js.map ``` {% alert level="danger" %} If the sum of the file size for `javascript.364758.min.js` and `javascript.364758.js.map` exceeds the 500 MB limit, reduce it by configuring your bundler to split the source code into multiple smaller chunks. For more information, see [Code Splitting with WebpackJS](https://webpack.js.org/guides/code-splitting/). {% /alert %} ## Upload your source maps{% #upload-your-source-maps %} To upload your source maps, choose one of the following matching methods: Debug ID (recommended) or service and version. Debug IDs enable source map resolution across micro frontends. {% tab title="Debug ID (Recommended)" %} Debug IDs associate a JavaScript bundle with its source map without relying on the bundle URL, service, or release version. Choose one of the following upload methods. #### Datadog Build Plugins{% #datadog-build-plugins %} Datadog Build Plugins can inject debug IDs and upload source maps directly during the build. You do not need to install or run `datadog-ci` separately. Debug ID support requires [Datadog Build Plugins version 3.3.0](https://github.com/DataDog/build-plugins/releases/tag/v3.3.0) or later. Enable debug ID injection and source map uploads in your build plugin: ```javascript datadogWebpackPlugin({ auth: { apiKey: process.env.DATADOG_API_KEY, site: 'datadoghq.com', }, sourcemaps: { debugId: true, upload: true, }, }); ``` The plugin uploads each source map with the debug ID injected into its corresponding JavaScript bundle. This example uses webpack. See [Datadog Build Plugins](https://docs.datadoghq.com/real_user_monitoring/application_monitoring/browser/build_plugins/source_maps.md) for installation and configuration instructions for other supported bundlers. #### `datadog-ci`{% #datadog-ci %} Debug ID support requires [`@datadog/datadog-ci` version 5.24.0](https://github.com/DataDog/datadog-ci/releases/tag/v5.24.0) or later. 1. Add `@datadog/datadog-ci` to your `package.json` file (make sure you're using the latest version). 1. [Create a dedicated Datadog API key](https://app.datadoghq.com/organization-settings/api-keys) and export it as an environment variable named `DD_API_KEY`. 1. For sites other than US1, configure the CLI by exporting `DD_SITE` with your [Datadog site](https://docs.datadoghq.com/getting_started/site.md). 1. Inject debug IDs after the build: ```bash datadog-ci sourcemaps inject /path/to/dist ``` 1. Upload the source maps and corresponding JavaScript bundles: ```bash datadog-ci sourcemaps upload /path/to/dist --debug-id ``` Do not pass `--service`, `--release-version`, or `--minified-path-prefix` with `--debug-id`. The `inject` command modifies JavaScript bundles and source maps in place. Run it after the build and before generating byte-dependent artifacts such as SRI hashes, compressed assets, signatures, or checksum manifests. Deploy the same modified artifacts that you upload. {% /tab %} {% tab title="Service and version" %} To upload source maps using a service and version, add an extra step to your CI pipeline that runs the `datadog-ci sourcemaps upload` command. It scans the `dist` directory and subdirectories to automatically upload source maps with the relevant minified files. {% callout %} # Important note for users on the following Datadog sites: app.datadoghq.com 1. Add `@datadog/datadog-ci` to your `package.json` file (make sure you're using the latest version). 1. [Create a dedicated Datadog API key](https://app.datadoghq.com/organization-settings/api-keys) and export it as an environment variable named `DD_API_KEY`. 1. Run the following command once per service in your application: ```bash datadog-ci sourcemaps upload /path/to/dist \ --service my-service \ --release-version v35.2395005 \ --minified-path-prefix https://hostname.com/static/js ``` {% /callout %} {% callout %} # Important note for users on the following Datadog sites: app.datadoghq.eu, us3.datadoghq.com, us5.datadoghq.com, app.ddog-gov.com, us2.ddog-gov.com, ap1.datadoghq.com, ap2.datadoghq.com, uk1.datadoghq.com 1. Add `@datadog/datadog-ci` to your `package.json` file (make sure you're using the latest version). 1. [Create a dedicated Datadog API key](https://app.datadoghq.com/organization-settings/api-keys) and export it as an environment variable named `DD_API_KEY`. 1. Configure the CLI to upload files to the {% placeholder "user-datadog-site-name" /%} site by exporting two environment variables: `export DATADOG_SITE=` and `export DATADOG_API_HOST=api.`. 1. Run the following command once per service in your application: ```bash datadog-ci sourcemaps upload /path/to/dist \ --service my-service \ --release-version v35.2395005 \ --minified-path-prefix https://hostname.com/static/js ``` {% /callout %} To minimize overhead on your CI's performance, the CLI is optimized to upload as many source maps as you need in a short amount of time (typically a few seconds). **Note**: Re-uploading a source map does not override the existing one if the version has not changed. The `--service` and `--release-version` parameters must match the `service` and `version` tags on your Error Tracking events, RUM events, and browser logs. For more information on how to setup these tags, refer to the [Browser SDK initialization documentation](https://docs.datadoghq.com/real_user_monitoring/application_monitoring/browser/setup.md#initialization-parameters) or [Browser Logs Collection documentation](https://docs.datadoghq.com/logs/log_collection/javascript.md#initialization-parameters). {% alert level="info" %} If you have defined multiple services in your application, run the CI command as many times as there are services, even if you have one set of sourcemaps for the entire application. {% /alert %} By running the command against the example `dist` directory, Datadog expects your server or CDN to deliver the JavaScript files at `https://hostname.com/static/js/javascript.364758.min.js` and `https://hostname.com/static/js/subdirectory/javascript.464388.min.js`. Only source maps with the `.js.map` extension work to correctly unminify stack traces. Source maps with other extensions such as `.mjs.map` are accepted but do not unminify stack traces. {% alert level="info" %} If you are serving the same JavaScript source files from different subdomains, upload the related source map once and make it work for multiple subdomains by using the absolute prefix path instead of the full URL. For example, specify `/static/js` instead of `https://hostname.com/static/js`. {% /alert %} {% /tab %} See all uploaded symbols and manage your source maps on the [Explore RUM Debug Symbols](https://app.datadoghq.com/source-code/setup/rum) page. ### Link stack frames to your source code{% #link-stack-frames-to-your-source-code %} If you run `datadog-ci sourcemaps upload` within a Git working directory, Datadog collects repository metadata. The `datadog-ci` command collects the repository URL, the current commit hash, and the list of file paths in the repository that relate to your source maps. For more details about Git metadata collection, refer to the [datadog-ci documentation](https://github.com/DataDog/datadog-ci/tree/master/packages/base/src/commands/sourcemaps#link-errors-with-your-source-code). Datadog displays links to your source code on unminified stack frames. ## Troubleshooting debug ID uploads{% #troubleshooting-debug-id-uploads %} ### Inspect local source maps{% #inspect-local-source-maps %} To find the local source map for a specific debug ID, run: ```bash datadog-ci sourcemaps find /path/to/dist --debug-id 12345678-1234-1234-1234-123456789abc ``` To find source maps that do not contain a debug ID, run: ```bash datadog-ci sourcemaps find /path/to/dist --missing-debug-id ``` The `find` command only inspects local `*.js.map` files. It does not confirm whether Datadog received an artifact. ## Troubleshoot errors with ease{% #troubleshoot-errors-with-ease %} Without access to the file path and the line number, a minified stack trace is not helpful in troubleshooting your code base. Also, the code snippet is minified (which means there is one long line of transformed code), making the troubleshooting process more difficult. The following example displays a minified stack trace: {% image source="https://docs.dd-static.net/images/real_user_monitoring/error_tracking/minified_stacktrace.3aeaa2bb1b1044d31b7e2a0a75da3c7c.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/real_user_monitoring/error_tracking/minified_stacktrace.3aeaa2bb1b1044d31b7e2a0a75da3c7c.png?auto=format&fit=max&w=850&dpr=2 2x" alt="Error Tracking Minified Stack Trace" /%} On the other hand, an unminified stack trace provides you with all the context you need for quick, seamless troubleshooting. For stack frames that relate to your source code, Datadog also generates a direct link to your repository: {% image source="https://docs.dd-static.net/images/real_user_monitoring/error_tracking/unminified_stacktrace.03b2959e8867c8dea6454fb3cf58ebb2.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/real_user_monitoring/error_tracking/unminified_stacktrace.03b2959e8867c8dea6454fb3cf58ebb2.png?auto=format&fit=max&w=850&dpr=2 2x" alt="Error Tracking Unminified Stack Trace" /%} ## Further Reading{% #further-reading %} Additional helpful documentation, links, and articles: - [Get started with Error Tracking](https://docs.datadoghq.com/real_user_monitoring/error_tracking.md) - [Visualize your Error Tracking data in the Explorer](https://docs.datadoghq.com/real_user_monitoring/error_tracking/explorer.md) - [Tracking errors with RUM for JavaScript Web Applications](https://learn.datadoghq.com/courses/tracking-errors-rum-javascript) - [A practical guide to React error monitoring](https://www.datadoghq.com/blog/a-practical-guide-to-react-error-monitoring/) - [Sourcemaps command reference](https://github.com/DataDog/datadog-ci/tree/master/packages/base/src/commands/sourcemaps)