Skip to content

Latest commit

 

History

History
118 lines (88 loc) · 5.29 KB

MIGRATION.md

File metadata and controls

118 lines (88 loc) · 5.29 KB
Raw

Migration Guide

This document serves as a migration guide, documenting all breaking changes between major versions of the Sentry bundler plugins.

Upgrading to 2.x

  • Removed injectReleasesMap option. If you need to inject values based on the build, please use your bundler's way of injecting values (rollup, vite, webpack, esbuild).
  • The minimum compatible version of rollup is version 3.2.0.
  • Removed functionality for the releaseInjectionTargets option.
  • @sentry/bundler-plugin-core will no longer export the individual plugins but a factory function to create them.
  • Removed customHeader option in favor of headers option which allows for multiple headers to be attached to outgoing requests.
  • The cliBinaryExists function was renamed to sentryCliBinaryExists
  • Removed the configFile option. Options should now be set explicitly or via environment variables. This also means that .sentryclirc files will no longer work as a means of configuration. Please manually pass in options, or use a configuration file (Webpack plugin docs, Vite plugin docs, esbuild plugin docs, Rollup plugin docs).
  • The minimum supported Node.js version is now 14 and newer.
  • Removed dryRun option.

Upgrading from 1.x to 2.x (Webpack Plugin Only)

Version 2 of @sentry/webpack-plugin is a complete rewrite of version 1, relying on bundler-agnostic code (based on unjs/unplugin). While we tried to keep changes to v1 of the webpack plugin minimal, a adjustments are nevertheless necessary:

Initialization and Required Values

Previously, to use the plugin, you had to create a new class of the SentryCLIPlugin class. In version 2, you simply need to call a function and pass the initialization options to it:

// old initialization:
import SentryCliPlugin from "@sentry/webpack-plugin";
new SentryCliPlugin({
  // ... options
});

// new initialization:
import { sentryWebpackPlugin } from "@sentry/webpack-plugin";
sentryWebpackPlugin({
  // ... options
});

Removal of include for sourcemap option

The include option was removed in favour of the new sourcemaps option. If you cannot migrate to the sourcemaps, include is still avaliable as the uploadLegacySourcemaps option.

Use the sourcemaps.assets and sourcemaps.ignore options to indicate to the plugin which sourcemaps should be uploaded to Sentry. The plugin now also exposes sourcemaps.deleteAfterUpload to delete your sourcemaps after they have been uploaded to Sentry. With the sourcemaps options, you no longer need to set filename transforms like urlPrefix because the plugin uses a new debug IDs system to associate sourcemaps to your bundles.

// old initialization:
import SentryWebpackPlugin from "@sentry/webpack-plugin";
new SentryWebpackPlugin({
  include: {
    paths: ["./path1", "./path2"],
    ignore: ["./path2/ignore"],
    urlPrefix: "~/static/js",
  },
});

// new initialization:
import { sentryWebpackPlugin } from "@sentry/webpack-plugin";
sentryWebpackPlugin({
  sourcemaps: {
    assets: ["./path1/**", "./path2/**"],
    ignore: ["./path2/ignore/**"],
    deleteFilesAfterUpload: ["./path1/**/*.map", "./path2/**/*.map"],
  },
});

Upgrading from 0.3.x to 0.4.x

Replacing default exports with named exports

Previously all the plugins were exported as default exports. Moving forward, with version 0.4.x of the plugins, all exports become named exports:

import sentryVitePlugin from "@sentry/vite-plugin";
// becomes
import { sentryVitePlugin } from "@sentry/vite-plugin";

import sentryEsbuildPlugin from "@sentry/esbuild-plugin";
// becomes
import { sentryEsbuildPlugin } from "@sentry/esbuild-plugin";

import sentryRollupPlugin from "@sentry/rollup-plugin";
// becomes
import { sentryRollupPlugin } from "@sentry/rollup-plugin";

Renaming of Options type export

The Options type was a bit too generic for our taste so we renamed it:

import type { Options } from "@sentry/vite-plugin";
// becomes
import type { SentryVitePluginOptions } from "@sentry/vite-plugin";

import type { Options } from "@sentry/esbuild-plugin";
// becomes
import type { SentryEsbuildPluginOptions } from "@sentry/esbuild-plugin";

import type { Options } from "@sentry/rollup-plugin";
// becomes
import type { SentryRollupPluginOptions } from "@sentry/rollup-plugin";

Behavioral change of releaseInjectionTargets

Previously the plugins injected a Sentry release value into every module that was processed. This approach caused problems in some cases so moving forward, they will only inject the release value into entrypoints by default.

In case you need more fine grained control over which modules should have a release value, you can use the releaseInjectionTargets option.

Removal of customHeader option

We removed the customHeader option in favor of the headers option.