Get readable crash reports in the Crashlytics dashboard (Web)

Select platform: iOS+ Android Web Flutter Unity


Web apps compile, minify, and scramble code names in production to optimize network bundling. Without source maps, crash reports in the Crashlytics dashboard show minified and obfuscated stack traces.

To de-obfuscate your stack traces and display original file names and line numbers in your error reports, use the Firebase CLI command to upload your source maps (.js.map files) to Firebase.

Prerequisites

Before uploading source maps, ensure that you have Firebase CLI v15.35.0 or later installed. Learn how to install or update the Firebase CLI.

Step 1: Enable source map generation in your framework build

Configure your frontend framework or bundler to generate production source (.js.map) files during your app build process:

Angular

In Angular, you must configure the sourceMap option inside your angular.json workspace file or pass the --source-map CLI override flag:

Option 1 (recommended): Modify angular.json

Open your angular.json file and locate the specific build configuration you want to target (such as development or production). Set the sourceMap parameter under the exact options or configurations block:

"projects": {
  "APP_NAME": {
    "architect": {
      "build": {
        "options": {
          "sourceMap": true
        },
        "configurations": {
          "production": {
            "sourceMap": {
              "scripts": true,
              "vendor": false
            }
          }
        }
      }
    }
  }
}

Option 2: Command-line override

If you only need source maps for a one-off verification build or debugging session, append the --source-map flag directly to your Angular CLI build command:

ng build --configuration production --source-map

Next.js

Update your next.config.ts (or next.config.js) file to enable browser source map generation during production builds by setting productionBrowserSourceMaps to true:

// next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  // Enable browser source map emission for Crashlytics stack trace de-obfuscation
  productionBrowserSourceMaps: true,
  // ... rest of your Next.js configuration
};

export default nextConfig;

Next.js stores generated client bundles and source map .js.map files inside the .next directory in your project root.

React / Vite

If your React app uses Vite as its build bundler, update your vite.config.ts file to emit source maps inside its build options:

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  build: {
    // Emit sourcemap files for Crashlytics upload
    sourcemap: true,
  },
});

Vite stores generated output bundles and .js.map files inside the dist directory by default.

Step 2: Upload source maps using the Firebase CLI

After your framework has built your production bundles and generated .js.map files, upload the source maps using the firebase crashlytics:sourcemap:upload command:

firebase crashlytics:sourcemap:upload \
  --project PROJECT_ID \
  --app FIREBASE_APP_ID \
  --debug DIRECTORY

This command recursively searches for all .js.map files within the supplied DIRECTORY path (dist or .next) and uploads them to Cloud Storage for symbol mapping.

Step 3: Handle source maps

Generating source maps alongside your web app assets can expose them to public browser requests, potentially causing your original source code to be leaked. You can prevent this without losing de-obfuscated stack traces by either configuring your web server to deny public access to .js.map files, or by passing the --clean flag to firebase crashlytics:sourcemap:upload to automatically delete .js.map files from your local build directory after uploading them to Firebase.

Automate in your build pipeline

To automatically upload source maps to Crashlytics and delete the local .js.map files before deployment, update your build script in your package.json file to pass the --clean flag to firebase crashlytics:sourcemap:upload:

Angular

"scripts": {
  "build": "ng build && firebase crashlytics:sourcemap:upload --project PROJECT_ID --app FIREBASE_APP_ID --clean --debug dist"
}

Next.js

"scripts": {
  "build": "next build && firebase crashlytics:sourcemap:upload --project PROJECT_ID --app FIREBASE_APP_ID --clean --debug .next"
}

React / Vite

"scripts": {
  "build": "vite build && firebase crashlytics:sourcemap:upload --project PROJECT_ID --app FIREBASE_APP_ID --clean --debug dist"
}

Next steps

  • Customize crash reports — Learn how to report handled exceptions, add custom keys to accompany your de-obfuscated stack traces, and configure sampling.