webpack-sentry-plugin

2.0.3 verified Sat Apr 25 auth: no javascript

Webpack plugin to upload source maps to Sentry for error tracking. Current stable version 2.0.3 supports webpack 4 & 5 and Node >= 6. Works by creating Sentry releases and uploading source maps automatically during the webpack build. Key differentiator: integrates directly with webpack's compilation lifecycle, supports release commits, filename transforms, and include/exclude filters. v2 rewrote the plugin API for webpack 4 hooks, breaking compatibility with webpack 1-3 (use v1 for those).

Common errors

error Error: Cannot find module 'webpack-sentry-plugin' ↓

cause Package not installed or imported incorrectly in ESM context.

fix

npm install webpack-sentry-plugin --save-dev and use require() as package is CommonJS only.

error TypeError: webpack_sentry_plugin is not a constructor ↓

cause Tried to use ES6 import syntax (e.g., import SentryPlugin from ...) which is not supported.

fix

Change to const SentryPlugin = require('webpack-sentry-plugin');

error Unhandled rejection: Error: Request failed with status code 401 ↓

cause Invalid or missing Sentry auth token or API key.

fix

Check SENTRY_AUTH_TOKEN env var is set and token has project:releases scope.

error SentryPlugin is not a plugin: Only 'tap', 'tapAsync', 'tapPromise' hooks are allowed. ↓

cause Using webpack 3 with v2 of the plugin, or using v1 with webpack 4.

fix

Match plugin version to webpack version: v1 for webpack 1-3, v2 for webpack 4-5.

Warnings

breaking v2.0.0 requires webpack >= 4 and Node >= 6. API changed to use webpack 4 hooks. ↓

fix If using webpack 1-3, stick with v1.x (latest 1.16.0). v2.0.0 removed webpack 1-3 support.

deprecated Configuration option 'apiKey' accepts both Sentry auth tokens and deprecated API keys. Sentry deprecated API keys in favor of auth tokens. ↓

fix Use a Sentry auth token instead of an API key. Generate from Sentry UI with 'project:releases' scope.

deprecated Option 'baseSentryURL' previously required trailing '/projects' but now should be provided without it (e.g. 'https://sentry.io/api/0'). ↓

fix Ensure baseSentryURL does not end with '/projects'.

gotcha The 'release' option can be a function receiving the compilation hash. Commonly misused as a string that is not unique per build. ↓

fix Use process.env.GIT_SHA or a function returning (hash) => `release-${hash}`.

gotcha Option 'filenameTransform' defaults to prefixing with '~/' for Sentry host wildcard. If you override, you must replicate that behavior if needed. ↓

fix Ensure transformed paths begin with '~/' if you want Sentry's host wildcard matching.

Install

npm install webpack-sentry-plugin

yarn add webpack-sentry-plugin

pnpm add webpack-sentry-plugin

Imports

SentryPlugin

wrong

import SentryPlugin from 'webpack-sentry-plugin';

correct

const SentryPlugin = require('webpack-sentry-plugin');

Package does not ship ES modules; must use CommonJS require().

default

wrong

import * as SentryPlugin from 'webpack-sentry-plugin';

correct

const SentryPlugin = require('webpack-sentry-plugin');

Default export is the plugin constructor. No named exports.

SentryPlugin

const { SentryPlugin } = require('webpack-sentry-plugin');

No named export exists. Only default export.

Quickstart

Configures webpack to output source maps and upload them to Sentry via the plugin.

const SentryPlugin = require('webpack-sentry-plugin');

module.exports = {
  devtool: 'source-map',
  plugins: [
    new SentryPlugin({
      organization: 'my-org',
      project: 'my-project',
      apiKey: process.env.SENTRY_AUTH_TOKEN || '',
      release: process.env.GIT_SHA || 'dev-release',
      include: /\.js$/
    })
  ]
};