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

Install source maps with bundlers

Configure Webpack or Rollup/Vite 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

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,
      }),
    ],
  };
});

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 regex pattern to match. Uploads all source maps by default
• bundleId: string - Bundle/build ID. Auto-generated by default
• 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. Default: false

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.