JS Error Hub

Vite Build Settings for Accurate Stack Traces

Configure Vite’s Rollup-based build pipeline to emit precise, environment-specific source maps. This guide details build flags, output formatting, and CI/CD integration for reliable error symbolication without exposing sensitive source code. Aligning your pipeline with established Source Map Generation & Stack Trace Debugging workflows ensures consistent error tracking across staging and production environments.

Key implementation objectives:

  • Optimize build.sourcemap for production vs. staging parity requirements
  • Configure Rollup output formats to preserve original file paths during chunking
  • Implement secure artifact upload workflows for observability platforms
  • Validate stack trace accuracy across minified and dynamically imported modules

Core Vite Build Configuration for Source Maps

Define baseline vite.config.js settings to control sourcemap generation strategy and output location. Set build.sourcemap to 'hidden' or 'inline' based on environment requirements. Explicitly configure build.rollupOptions.output to preserve sourcemapFile and assetFileNames paths. This prevents path collisions during dynamic chunk splitting.

import { defineConfig } from 'vite';

export default defineConfig(({ mode }) => ({
 build: {
 sourcemap: mode === 'production' ? 'hidden' : 'inline',
 minify: 'esbuild',
 rollupOptions: {
 output: {
 sourcemapFile: '[name]-[hash].js.map',
 assetFileNames: 'assets/[name]-[hash][extname]'
 }
 }
 }
}));

The configuration above demonstrates conditional build.sourcemap assignment. It enforces explicit Rollup output formatting to maintain deterministic file naming during production builds.

Rollup Plugin Integration & Chunk Optimization

Manage how Vite delegates sourcemap generation to Rollup during code splitting and minification. Override build.minify to 'esbuild' while preserving line mappings via esbuildOptions. Aggressive whitespace collapsing can corrupt column accuracy if mapping flags are omitted.

Verify that your output includes sourcesContent to embed original source code directly into the .map file. Reference the Understanding Source Map v3 Specification and Formats documentation to validate mapping structure compliance. This prevents observability platforms from failing to fetch external repository files during symbolication.

For cross-bundle trace continuity, integrate @rollup/plugin-sourcemaps when merging third-party vendor chunks. Ensure plugin execution order places sourcemap generation after transpilation but before final asset emission.

Environment-Specific Build Flags & CI/CD Workflows

Automate conditional sourcemap generation and secure artifact handling across deployment stages. Use process.env.NODE_ENV or Vite’s mode parameter to toggle build.sourcemap between 'true' (dev) and 'hidden' (prod). Integrate post-build scripts to strip .map files from CDN deployments.

Compare this conditional logic against Configuring Webpack for Production Source Maps to standardize cross-bundler CI pipelines. Consistent environment parity reduces debugging overhead during incident response.

#!/usr/bin/env node
const fs = require('fs');
const path = require('path');
const distDir = path.resolve(__dirname, 'dist');
const mapFiles = fs.readdirSync(distDir).filter(f => f.endsWith('.map'));

mapFiles.forEach(f => {
 const mapPath = path.join(distDir, f);
 uploadToSecureStorage(mapPath);
 fs.unlinkSync(mapPath);
});

This script automates extraction of .map files from the public distribution directory before CDN sync. It ensures hidden source maps remain inaccessible to end users while preserving them for secure observability uploads.

Validation & Stack Trace Verification

Execute pre-deployment checks to guarantee minified errors resolve to original TypeScript/JSX sources. Run vite build --mode staging and trigger synthetic errors to test mapping fidelity. Verify the sources array paths match your repository structure for accurate reverse mapping.

Implement the secure artifact extraction patterns detailed in How to generate hidden source maps in Vite for production observability uploads. Automated validation prevents mapping drift during dependency upgrades.

import { expect, test } from 'vitest';

test('stack trace resolves to original source', async () => {
 try {
 throw new Error('Test mapping fidelity');
 } catch (err) {
 const stack = err.stack || '';
 expect(stack).toContain('src/components/App.tsx');
 expect(stack).not.toContain('dist/assets/');
 }
});

The Vitest suite validates that minified error stacks correctly reference original TypeScript paths. It explicitly asserts the exclusion of build artifact directories, confirming successful reverse mapping.

Common Configuration Mistakes

  • Enabling build.sourcemap: true in production: Exposes raw source code to end-users via public .map files. This creates security vulnerabilities and unnecessarily increases CDN payload size.
  • Omitting sourcesContent in Rollup output: Results in missing original code context during symbolication. Observability platforms are forced to fetch files from version control, increasing latency and failure rates.
  • Mismatched sourcemapBaseUrl in error tracking SDKs: Causes reverse mapping failures when the deployed asset path differs from the local build directory structure. Always align SDK base URLs with your CDN prefix.
  • Using esbuild minification without preserving line mappings: Aggressive minification collapses whitespace and merges statements. This corrupts stack trace line/column accuracy unless proper sourcemap flags are explicitly configured.

Frequently Asked Questions

Should I use hidden, inline, or true for build.sourcemap in Vite? Use hidden for production to generate .map files without exposing them publicly, inline for staging to embed mappings directly in JS, and avoid true in production to prevent public source exposure.

How does Vite handle source maps for dynamically imported chunks? Vite delegates chunk splitting to Rollup, which automatically generates separate .map files per chunk. Ensure rollupOptions.output.sourcemapFile uses [name]-[hash].js.map to prevent path collisions.

Why are my stack traces still pointing to minified code after enabling sourcemaps? Verify that build.minify is set to esbuild or terser with proper mapping flags. Confirm sourcesContent is included in the output and ensure your observability SDK is configured with the correct sourcemapBaseUrl.

Can I exclude specific files from source map generation? Yes. Configure build.rollupOptions.plugins with a custom Rollup plugin that intercepts the generateBundle hook. Filter out .map generation for specified entry points or vendor libraries before final asset emission.