Skip to main content

Source Maps

Source maps are essential for debugging minified production code. They allow Palette to map minified stack traces back to your original source code, making it easier to identify and fix issues in production.

Why Upload Source Maps?​

When your JavaScript code is minified for production:

  • Variable and function names are shortened
  • Code is compressed and optimized
  • Stack traces become difficult to read

Source maps solve this by providing a mapping between your minified code and original source files, enabling:

  • Readable stack traces in error reports and profiler views
  • Accurate line numbers pointing to your original code
  • Better debugging of production issues

Upload Methods​

Palette provides three ways to upload source maps:

1. CLI Tool​

Upload source maps using the command line interface - ideal for custom build processes or CI/CD pipelines.

npx @palette.dev/cli upload --key YOUR_ASSET_KEY --version 1.0.0 ./dist

See the CLI documentation for detailed usage and options.

2. Webpack Plugin​

Automatically upload source maps during your Webpack build process.

import PalettePlugin from "@palette.dev/webpack-plugin";

export default {
  plugins: [
    new PalettePlugin({
      key: process.env.PALETTE_ASSET_KEY,
      enableSourceMaps: process.env.NODE_ENV === "production",
    }),
  ],
};

See the Webpack Plugin documentation for configuration details.

3. Vite Plugin​

Seamlessly upload source maps in Vite projects.

import palette from "@palette.dev/plugin-vite";

export default {
  plugins: [
    palette({
      key: process.env.VITE_PALETTE_ASSET_KEY,
      enableSourceMaps: process.env.NODE_ENV === "production",
    }),
  ],
};

See the Vite Plugin documentation for configuration details.

Best Practices​

Use Version Identifiers​

Always specify a unique version when uploading source maps to ensure Palette can match errors to the correct source maps:

// Use git commit SHA
release: process.env.GIT_COMMIT_SHA;

// Use package version
release: require("./package.json").version;

// Use build timestamp
release: new Date().toISOString();

Secure Your Asset Key​

Never commit your asset key to version control:

# .env.local (add to .gitignore)
PALETTE_ASSET_KEY=your-key-here

Upload in CI/CD​

Upload source maps as part of your deployment pipeline to ensure they're always in sync with your deployed code.

Remove Source Maps from Production​

After uploading, remove source maps from your production servers to prevent exposing source code:

# CLI - remove after upload
palette upload --key YOUR_KEY --version 1.0.0 ./dist
rm -rf ./dist/**/*.map
// Or use plugin option
deleteAfterUpload: true;

Troubleshooting​

Common Issues​

"Source maps not found for this release"

  • Verify you're uploading source maps with the correct version identifier

"Invalid source map format"

  • Ensure your bundler is generating standard source map format (v3)

"Source maps uploaded but not applied"

  • Check that the sourceMappingURL in your JS files matches the uploaded source map filenames
© 2025 Redraw, Inc.