Documentation Grafana Cloud Monitor applications Frontend Observability Configure Source map uploads Upload with bundlers

Upload source maps with bundlers

Configure Webpack, Rollup/Vite, or esbuild bundlers to automatically upload source maps to Grafana Cloud during builds.

Faro bundler plugins support client-side rendered applications only. Server-side rendering isn’t supported. Next.js client-side apps may need _next/ path adjustments using the nextjs option.

Webpack plugin

Bash Copy

npm install --save-dev @grafana/faro-webpack-plugin

or

Bash Copy

yarn add --dev @grafana/faro-webpack-plugin

Rollup/Vite plugin

Bash Copy

npm install --save-dev @grafana/faro-rollup-plugin

or

Bash Copy

yarn add --dev @grafana/faro-rollup-plugin

Esbuild plugin

Bash Copy

npm install --save-dev @grafana/faro-esbuild-plugin

or

Bash Copy

yarn add --dev @grafana/faro-esbuild-plugin

Obtain an API key

To use the Faro JavaScript bundler plugins, you must generate a token for the API key value with the necessary permissions to upload source maps to Grafana Cloud. To generate a token, follow these steps:

1. Navigate to the Grafana website.
2. Sign in to your account and then click My Account in the top right corner.
3. In the sidebar under Security, click Access Policies and then click Create access policy.
4. Select the sourcemaps:read, sourcemaps:delete, and sourcemaps:write scopes from the drop-down list.
5. After creating your access policy, click Add token in the card for your newly created policy.
6. Create the token and be sure to copy the token value, as you won’t be able to see it again.

After you have generated a token with the API key value, you can use it in the Faro JavaScript bundler plugins to upload your source maps to Grafana Cloud. Use the generated token value as the apiKey value in the configuration options for the bundler plugins.

For best practices, store your token in a secure location and don’t expose it in your source code. Consider using environment variables or a secrets manager to securely store and access your API key.

Webpack configuration

Add the plugin to your webpack.config.js:

JavaScript Copy

// other imports
import FaroSourceMapUploaderPlugin from '@grafana/faro-webpack-plugin';

module.exports = {
  // other configs
  plugins: [
    // other plugins
    new FaroSourceMapUploaderPlugin({
      appName: '$your-app-name',
      endpoint: '$your-faro-sourcemap-api-url',
      apiKey: '$your-api-key',
      appId: '$your-app-id',
      stackId: '$your-stack-id',
      gzipContents: true,
      // Set skipUpload: true to upload later with CLI
      // skipUpload: true,
    }),
  ],
};

Rollup/Vite configuration

Add the plugin to your rollup.config.js or vite.config.js:

JavaScript Copy

// other imports
import faroUploader from '@grafana/faro-rollup-plugin';

export default defineConfig(({ mode }) => {
  return {
    // other configs
    plugins: [
      // other plugins
      faroUploader({
        appName: '$your-app-name',
        endpoint: '$your-faro-sourcemap-api-url',
        apiKey: '$your-api-key',
        appId: '$your-app-id',
        stackId: '$your-stack-id',
        gzipContents: true,
        // Set skipUpload: true to upload later with CLI
        // skipUpload: true,
      }),
    ],
  };
});

Esbuild configuration

Add the plugin to your esbuild build script:

JavaScript Copy

import * as esbuild from 'esbuild';
import faroEsbuildPlugin from '@grafana/faro-esbuild-plugin';

await esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  outdir: 'dist',
  plugins: [
    faroEsbuildPlugin({
      appName: '$your-app-name',
      endpoint: '$your-faro-sourcemap-api-url',
      apiKey: '$your-api-key',
      appId: '$your-app-id',
      stackId: '$your-stack-id',
      gzipContents: true,
      // Set skipUpload: true to upload later with CLI
      // skipUpload: true,
    }),
  ],
});

Configuration options

Configure bundler plugins with these options:

Required options:

• appName: string - Application name that matches your Faro Web SDK configuration
• endpoint: string - Source map API endpoint from Frontend Observability > Settings > Source Maps > Configure source map uploads
• apiKey: string - API key with sourcemaps:read, sourcemaps:write, and sourcemaps:delete scopes
• appId: string - Application ID that matches your Faro Web SDK configuration
• stackId: string - Grafana Cloud stack ID

Optional options:

• outputPath: string - Override output directory path for source maps. Uses bundler output path by default
• outputFiles: string[] | RegExp - List of source map files or regular expression pattern to match. Uploads all source maps by default
• bundleId: string - Bundle/build ID. Auto-generated by default
• gitHash: string - Git commit hash to inject into the bundle. Resolved in order: explicit value → git rev-parse HEAD. Use this option to provide an explicit value when auto-detection won’t pick the right SHA (for example, multi-stage Docker builds without .git, or GitHub Actions pull_request events where HEAD is a synthetic merge commit). If neither resolves, no git hash is injected
• keepSourcemaps: boolean - Keep source maps in generated bundle after uploading. Default: false
• gzipContents: boolean - Compress source maps before uploading. Default: true
• verbose: boolean - Enable detailed logging during upload. Default: false
• skipUpload: boolean - Skip uploading during build and export bundle ID to environment file. Default: false
• maxUploadSize: number - Maximum upload size in bytes for single batch. Default: 30MB
• recursive: boolean - Recursively search subdirectories for source maps. Default: false
• nextjs: boolean - Webpack only. Prepend _next/ to file properties for Next.js compatibility. Only needed when your Next.js application has both client and server side code. If both prefixPath and nextjs are provided, they are combined as ${prefixPath}/_next/. Default: false
• proxy: string - Proxy URL to route source map uploads through. Supports HTTP and HTTPS proxies. Include credentials in the URL if authentication is required: http://username:password@proxy.example.com:8080
• prefixPath: string - Prefix to prepend to the file property in source maps. Useful when files in the browser appear in a different path hierarchy than the bundler is aware of (for example, when using a CDN where stack traces show cdn/index.js but the source map only shows index.js)
• prefixPathBasenameOnly: boolean - When true, strips any directory path from the source map file property before prepending prefixPath, keeping only the filename. Useful when assets are deployed flat to a CDN with no subdirectory structure. For example, if the source map’s file is assets/index.js and prefixPath is https://cdn.example.com/assets/, this produces https://cdn.example.com/assets/index.js instead of https://cdn.example.com/assets/assets/index.js. Only applies when prefixPath is set. Default: false

Link errors to commits (Suspect Commits)

The Suspect Commits feature in Frontend Observability surfaces the Git commit most likely responsible for an error on the error summary page, so you can jump from a stack trace to a candidate fix without leaving Grafana. Enabling commit hash injection adds a directly recorded signal: when an error first appears, the SDK reports the build’s SHA, and Suspect Commits pins that commit at the top of the candidate list.

To enable this, the bundler plugin injects the current commit hash into your built JavaScript at build time, the Faro Web SDK reads it, and includes it as meta.app.gitHash on every telemetry payload.

Minimum versions:

• @grafana/faro-web-sdk (and @grafana/faro-react): 2.7.0
• Bundler plugins: @grafana/faro-webpack-plugin 0.12.0, @grafana/faro-rollup-plugin 0.11.0, @grafana/faro-esbuild-plugin 0.6.0, @grafana/faro-metro-plugin 0.2.0
• CLI (for post-build injection): @grafana/faro-cli 0.10.0

The bundler plugin resolves the hash in this priority order:

1. Explicit gitHash value passed to the plugin
2. Auto-detected via git rev-parse HEAD at build time

If neither resolves, the plugin emits [Faro] Git hash could not be resolved to the build log and no hash is injected. The build still succeeds.

Auto-detection via git rev-parse HEAD:

When gitHash is not specified, the plugin runs git rev-parse HEAD during the build. This works for most local development environments and CI setups where the .git directory is present in the build context:

JavaScript Copy

new FaroSourceMapUploaderPlugin({
  appName: '$your-app-name',
  endpoint: '$your-faro-sourcemap-api-url',
  // ...other required options
  // gitHash auto-detected from git rev-parse HEAD
});

Explicit override:

Set gitHash explicitly when auto-detection won’t pick the right SHA:

• Multi-stage Docker builds, or any build context without access to .git
• GitHub Actions pull_request events, where git rev-parse HEAD and process.env.GITHUB_SHA both resolve to a synthetic merge commit that doesn’t exist on any branch — to point at the PR head, pass ${{ github.event.pull_request.head.sha }} through as an env var
• Any environment where the desired SHA differs from the local checkout

JavaScript Copy

new FaroSourceMapUploaderPlugin({
  appName: '$your-app-name',
  endpoint: '$your-faro-sourcemap-api-url',
  // ...other required options
  gitHash: process.env.FARO_GIT_HASH,
});

On GitHub Actions, expose the PR head SHA to the build step.

Use pull_request.head.sha so the injected SHA points at the PR head, not the synthetic merge commit GitHub creates for pull_request events:

YAML Copy

- name: build
  env:
    FARO_GIT_HASH: ${{ github.event.pull_request.head.sha || github.sha }}
  run: yarn build

Post-build injection via the Faro CLI:

If you can’t run the bundler plugin at build time (for example, you ship pre-built artifacts produced elsewhere), the @grafana/faro-cli package exposes an inject-git-hash command that mirrors inject-bundle-id and patches the hash into existing JavaScript artifacts after the fact:

Bash Copy

npx @grafana/faro-cli inject-git-hash \
  --app-name '$your-app-name' \
  --git-hash $(git rev-parse HEAD) \
  --files 'dist/**/*.js'

Refer to the faro-javascript-bundler-plugins repository for the full CLI reference.

Set gitHash directly in the Faro Web SDK configuration

If you don’t use the Faro bundler plugins, you can set app.gitHash directly when initializing the Faro Web SDK. Because browsers have no process.env, the commit SHA must be embedded into the bundle at build time:

1. Make the SHA available to the build:

For local builds:

Bash Copy

export GIT_HASH=$(git rev-parse HEAD)

For CI environments, use the appropriate environment variable:

• GitHub Actions: export GIT_HASH=$GITHUB_SHA
• Jenkins: export GIT_HASH=$GIT_COMMIT
• GitLab CI: export GIT_HASH=$CI_COMMIT_SHA

2. Configure your bundler to inline it.

For Create React App and Next.js, no extra config is needed — they automatically inline prefixed env vars. Set REACT_APP_GIT_HASH (CRA) or NEXT_PUBLIC_GIT_HASH (Next.js) instead of GIT_HASH in step 1, and reference it directly as process.env.REACT_APP_GIT_HASH / process.env.NEXT_PUBLIC_GIT_HASH.

For Vite, no extra configuration is needed — Vite embeds import.meta.env.VITE_*. Set VITE_GIT_HASH in step 1 and reference it as import.meta.env.VITE_GIT_HASH.

For Webpack, use DefinePlugin:

JavaScript Copy

// webpack.config.js
const webpack = require('webpack');

module.exports = {
  // ...
  plugins: [
    new webpack.DefinePlugin({
      'process.env.GIT_HASH': JSON.stringify(process.env.GIT_HASH),
    }),
  ],
};

For Rollup, use @rollup/plugin-replace:

JavaScript Copy

// rollup.config.js
import replace from '@rollup/plugin-replace';

export default {
  // ...
  plugins: [
    replace({
      preventAssignment: true,
      'process.env.GIT_HASH': JSON.stringify(process.env.GIT_HASH),
    }),
  ],
};

For esbuild, use the define option:

JavaScript Copy

// build.js
import * as esbuild from 'esbuild';

await esbuild.build({
  // ...
  define: {
    'process.env.GIT_HASH': JSON.stringify(process.env.GIT_HASH),
  },
});

3. Reference it in your Faro initialization:

JavaScript Copy

import { initializeFaro } from '@grafana/faro-web-sdk';

initializeFaro({
  url: '$your-faro-collector-url',
  app: {
    name: '$your-app-name',
    version: '1.0.0',
    gitHash: process.env.GIT_HASH, // or import.meta.env.VITE_GIT_HASH for Vite
  },
  // ...other config
});

Only the meta.app.gitHash check below applies when using this approach. The bundler plugins set window.__faroGitHash_<app-name> only.

Verify the commit hash is captured

After a successful build, you can confirm the hash flows end-to-end:

• Build log: grep for [Faro] Git hash could not be resolved — if the plugin couldn’t determine a SHA, this string appears in the build output. Its absence means the plugin resolved a hash successfully.
• Bundle: open DevTools console on a page using the bundle and run window.__faroGitHash_<your-app-name> — expect a 40-character SHA. (Bundler plugin path only.)
• Telemetry: in the browser Network tab, inspect a Faro /collect request — meta.app.gitHash should be set on the payload.

If the hash is missing, the most common cause is a build context without .git (multi-stage Docker, .dockerignore excluding .git) — refer to the Explicit override section to set gitHash explicitly.

Verify source maps

After building your application, verify uploads in Frontend Observability by navigating to your app > Settings > Source Maps. If you set skipUpload: true, complete the upload using the CLI.

For troubleshooting common issues, refer to Troubleshooting.