--- 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 --- # 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 %} The best way to upload source maps is to add an extra step in your CI pipeline and run the dedicated command from the [Datadog CLI](https://github.com/DataDog/datadog-ci/tree/master/packages/base/src/commands/sourcemaps). It scans the `dist` directory and subdirectories to automatically upload source maps with 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 `DATADOG_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, ap1.datadoghq.com, ap2.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 `DATADOG_API_KEY`. 1. Configure the CLI to upload files to the 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 %} 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. ## 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 %} - [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) - [Sourcemaps command reference](https://github.com/DataDog/datadog-ci/tree/master/packages/base/src/commands/sourcemaps)