Source maps

Upload source maps with each build to see the original file, function, line, and surrounding code in your issues.

Let your coding agent configure the uploads, or follow the manual setup. Use the Vite plugin for Vite apps and the CLI for AdonisJS, TypeScript, or another bundler.

Set up with your agent

Open your coding agent at the root of your repository and paste the prompt below. The agent inspects your build and deployment configuration before making changes. The prompt covers single apps, monorepos with separate frontends and APIs, and AdonisJS apps with Inertia.

Set up Monocle source map uploads in this repository. Read the setup guide:
https://monocle.sh/docs/sdks/source-maps

Inspect the repository instructions, workspaces, package scripts, compiler
and bundler configs, Dockerfiles, and CI workflows. Identify each deployed
JavaScript app, its build output, and the Monocle project that receives its
errors. Don't assume one app, one output directory, or one project per repo.
Ask me if you can't determine which Monocle project an app uses.

Configure uploads in each app's existing build or deployment workflow:

- For Vite output, use @monocle.sh/vite-plugin. Reuse it if already configured.
- For compiled Node.js output, use @monocle.sh/cli sourcemaps inject followed
  by sourcemaps upload. Enable source maps in the compiler if needed.
- For AdonisJS with Inertia, handle the Vite browser build and the compiled
  server build separately. Don't upload the browser output again with the CLI.
- For multiple APIs or other apps, configure each deployed build separately.
  Use the repository's package manager and actual output paths.

Run CLI uploads from a directory that contains the app's original sources.
Inject after the final build, upload before deployment, then remove .map files.
Deploy the injected JavaScript without rebuilding it. For Node.js, remove
--enable-source-maps from startup commands and NODE_OPTIONS.

Use a project token of the target Monocle project through MONOCLE_API_KEY in the build
environment. Never put a key in browser code, a VITE_ variable, or a tracked
file. For Docker builds, use build secrets. Tell me which CI secrets I need
to configure without asking me to paste their values into this conversation.

Keep existing SDK setup and unrelated build settings. Flag any app that
doesn't report errors to Monocle yet. Check the changed configuration with
the repository's available checks. Don't upload, deploy, or trigger a test
error without my approval.

Summarize the setup for each app, any missing secrets or SDK setup, and how
I can verify an original source frame in Monocle after deployment. Distinguish
checks you ran from uploads or error resolution that still need verification.

Before you start

Connect your app with the browser SDK or a Monocle Node.js agent. The SDK reports errors. The plugin and CLI upload the source maps that Monocle uses to resolve those errors.

Set MONOCLE_API_KEY in your CI secrets. Uploads require a project token, not a DSN or browser key. Legacy API keys also work.

Vite

The plugin generates source maps, injects debug IDs, uploads the files, and removes the maps from the build output. You don't need the CLI.

1. Install the plugin

   npm install -D @monocle.sh/vite-plugin

2. Add the plugin to Vite

   If you already use the plugin to report build versions, keep your existing configuration.

   import { defineConfig } from 'vite'
   import { monocle } from '@monocle.sh/vite-plugin'
   
   export default defineConfig({
   	plugins: [monocle()],
   })

3. Build with the project token

   Run your production build with MONOCLE_API_KEY available in the environment:

   npm run build

   Check the build log for [monocle] Source maps: and the uploaded or already uploaded file count.

Deploy the build output, then verify the stack trace.

Upload with the CLI

Run these steps from your project directory, where the original source files are available. Replace ./dist with your build output directory.

1. Generate source maps

   Enable source maps in your compiler or bundler, then build your app. Choose the configuration for your tool:

   AdonisJSTypeScriptOther bundlers

   The default AdonisJS tsconfig.json enables sourceMap. Build the app:

   node ace build

   Use ./build instead of ./dist in the following commands.

   For Node.js apps, remove --enable-source-maps from the server startup command, including NODE_OPTIONS. Monocle needs the compiled positions to resolve frames with the uploaded maps.

2. Inject debug IDs

   npx @monocle.sh/cli sourcemaps inject ./dist

   The command adds a debug ID to each JavaScript file and its source map. Run it after the build, before upload and deployment.

3. Upload the files

   With MONOCLE_API_KEY available in the environment, run:

   npx @monocle.sh/cli sourcemaps upload ./dist

   The command uploads the JavaScript files and their source maps. It skips files that Monocle already has.

4. Remove the maps and deploy

   After a successful upload, remove the maps from the output:

   find ./dist -name '*.map' -delete

   Deploy the injected JavaScript files. Don't rebuild after injection: the new files would no longer contain the debug IDs that match your upload.

RUN node ace build
RUN --mount=type=secret,id=monocle_api_key \
	MONOCLE_API_KEY=$(cat /run/secrets/monocle_api_key) \
	sh -c 'npx @monocle.sh/cli sourcemaps inject build && \
		npx @monocle.sh/cli sourcemaps upload build && \
		find build -name "*.map" -delete'

- uses: docker/build-push-action@v6
  with:
    secrets: monocle_api_key=${{ secrets.MONOCLE_API_KEY }}

Verify the stack trace

1. Check that the upload completed without errors for the build you deployed.
2. Trigger an error in that build and open the occurrence in Issues.
3. Check that a frame from your code shows the original source file, line, and surrounding code instead of a compiled position such as index-a1b2c3.js:1:18234.

Monocle matches files by debug ID, not by release, file name, or domain. You don't need to set a version for source maps. The same build can run in several environments without another upload.

If an error arrived before its source map, open the error again after the upload. Monocle resolves the frames when you view it.

Keep source maps private

Source maps can contain your original source code. Upload them to Monocle, but don't deploy the .map files to your public server. Hidden source maps omit the bundle's sourceMappingURL comment. They don't prevent someone from downloading a .map file that you deploy.

When a map lacks sourcesContent, the upload reads original files from disk. It reads only source files inside the project root, excluding hidden files, hidden directories, and node_modules. For the CLI, the project root is the working directory. For the Vite plugin, it is the Vite root. The upload reads source maps only inside the build output directory.

Troubleshooting