diff --git a/docs/error-reporting/platform-integrations/source-map.md b/docs/error-reporting/platform-integrations/source-map.md index 877c3aa330..260ed77c91 100644 --- a/docs/error-reporting/platform-integrations/source-map.md +++ b/docs/error-reporting/platform-integrations/source-map.md @@ -9,17 +9,24 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import useBaseUrl from '@docusaurus/useBaseUrl'; -The following steps guide you through configuring your JavaScript application to automatically upload sourcemap files during the project build. +The Backtrace debugger can highlight specific lines in your source code associated with frames in the callstack. This powerful capability can be enabled by uploading source and source maps. The following steps guide you through configuring your JavaScript application to automatically upload sourcemap files during the project build. ## What You'll Need - A Backtrace account ([log in](https://backtrace.io/login) or sign up for a [free trial license](https://backtrace.io/sign-up)). -- Your subdomain name (used to connect to your Backtrace instance). For example, `https://example-subdomain.sp.backtrace.io`. -- [Symbol submission token and URL](/error-reporting/project-setup/submission-url) +- A symbol submission URL with a `symbol:post` token for the `sourcemap` endpoint. [<detailed instructions>](/error-reporting/project-setup/submission-url) ## Creating and Uploading Source Maps -**Step 1: Enable Source Maps for Your Application** +Follow these steps to create and upload source maps with every build of your application: +1. [Enable source maps](#step-1-enable-source-maps-for-your-application) +1. [Install the `backtrace-js` command line tool](#step-2-install-backtrace-js) +1. [Create a configuration file for `backtrace-js`](#step-3-create-a-backtracejsrc-configuration-file) + + +### Step 1: Enable Source Maps for Your Application + +Source maps are automatically generated with most JavaScript frameworks. Please follow these instructions if you are using a framework that does not automatically generate source maps. -**Step 2: Configure @backtrace-labs/javascript-cli** +--- +### Step 2: Install `backtrace-js` + +Install the `backtrace-js` command line tool and update your build scripts to run it. `backtrace-js` can be run from the command line, but it is most efficient to use a configuration file which we will create in the next step. 1. Install `@backtrace-labs/javascript-cli` as a dev dependency: ```bash - npm install --save-dev @backtrace-labs/javascript-cli + npm install -g --save-dev @backtrace-labs/javascript-cli ``` -2. Add the following scripts to your `package.json` file: +2. Add the following script to `package.json` to process and upload source maps: ```json "scripts": { - "backtrace:process": "backtrace-js process OUTPUT_DIRECTORY", - "backtrace:upload": "backtrace-js upload OUTPUT_DIRECTORY UPLOAD_OPTIONS" + // highlight-next-line + "backtrace:sourcemap": "backtrace-js run", } ``` -You can also use `npx` and skip adding the dependency: +3. Update the build step in `package.json` to process and upload source maps with every build: -```json -"scripts": { - "backtrace:process": "npx --package @backtrace-labs/javascript-cli backtrace-js process OUTPUT_DIRECTORY", - "backtrace:upload": "npx --package @backtrace-labs/javascript-cli backtrace-js upload OUTPUT_DIRECTORY UPLOAD_OPTIONS" -} -``` - -Replace `OUTPUT_DIRECTORY` with the path to the directory where your transpiled scripts are stored. - -Replace `UPLOAD_OPTIONS` with `--url `, obtained from [the symbol submission URL](#acquire-a-symbol-submission-token-and-url). + ```json + "scripts": { + // highlight-next-line + "build": " && npm run backtrace:sourcemap" + } + ``` -### Configuration File +--- +### Step 3: Create a `.backtracejsrc` configuration file -Instead of providing options in script argument lines, you can configure them in the `.backtracejsrc` configuration file: +Create a `.backtracejs` configuration file in the root of your project with these settings to process source maps, add source and upload to Backtrace. -```jsonc +```json { - "path": "OUTPUT_DIRECTORY", - "upload": { - "url": "your upload URL" - } + // highlight-next-line + "path": "", + "run": { + "process": true, + "add-sources": true, + "upload": true + }, + "upload": { + // highlight-next-line + "url": "", + "include-sources": true + } } ``` -For more details, consult `@backtrace-labs/javascript-cli` [README](https://github.com/backtrace-labs/backtrace-javascript/blob/main/tools/cli/README.md). - -**Step 3: Set Up Automatic Processing and Upload** +- Replace `` with the path to the directory where your transpiled scripts are stored. +- Follow [<these instructions>](/error-reporting/project-setup/submission-url) to create the `` with a `symbol:post` token for the `sourcemap` endpoint. -To process and upload your artifacts, you must first run `npm run backtrace:process` and then `npm run backtrace:upload`. +:::info Source Code Upload + Source files can be embedded in source maps and included in the upload to Backtrace. The configuration above is constructed to do this. -To ensure that this is done automatically, you can add these commands to your production script: + Alternatively, if you do not wish to upload source files directly to Backtrace, you can integrate your source repository. To do so, omit `add-sources` and `include-sources` and follow the steps in the [Source Code](../../project-setup/source-code/) document. +::: -```json -"scripts": { - "build": "my current build command && npm run backtrace:process && npm run backtrace:upload" -} +See `backtrace-js --help` or go to [`@backtrace-labs/javascript-cli`](https://github.com/backtrace-labs/backtrace-javascript/blob/dev/tools/cli) for additional command line and configuration options. + +:::note Troubleshooting + Source map processing will halt on error with a description. Use a --verbose command line switch to output extended information for troubleshooting. + + __File processing errors__ + + File processing may halt on a specific file for valid reasons. For instance, a source map may not produced for a script file. Processing for such a file can be skipped with an exclude object in `.backtracejsrc` + + ```json + { + "path": "", + // highlight-start + "exclude": [ + // highlight-next-line + "./app1/build/static/js/file.chunk.js" + ] + // highlight-end + "run": { + ... + } ``` + Alternatively, all processing errors can be treated as warnings or other errors levels. + ```json + { + "path": "", + // highlight-start + "asset-error-behavior": "warn", + // highlight-end + "run": { + ... + } + ``` + +::: + ## Project Bundlers