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

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

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.