|
2 | 2 |
|
3 | 3 | This document serves as a migration guide, documenting all breaking changes between major versions of the Sentry bundler plugins. |
4 | 4 |
|
5 | | -## [Unreleased] Upgrading from 1.x to 2.x |
| 5 | +## [Unreleased] Upgrading from 1.x to 2.x (Webpack Plugin Only) |
6 | 6 |
|
7 | | -Version 2 of `@sentry/webpack-plugin` is a complete rewrite of version 1. |
8 | | -Version 2 no longer requires `sentry-cli` underneath, meaning the plugin no longer downloads a binary but implements all its functionality natively. |
9 | | - |
10 | | -### Removal of Implicit Environment Variable Usage |
11 | | - |
12 | | -Version 2 of the Webpack plugin removes the implicit passing of plugin parameters via environment variables. |
13 | | -Previously, it was possible to specify values as environment variables, such as SENTRY_AUTH_TOKEN, but to never mention them in the plugin init options. |
14 | | -In this version, you'll have to specify these values in the options. |
15 | | -Note that this makes certain option fields explicitly required now which were previously only implicitly required (see [Initialization and Required Values](#initialization-and-required-values)). |
| 7 | +Version 2 of `@sentry/webpack-plugin` is a complete rewrite of version 1, relying on bundler-agnostic code (based on [unjs/unplugin](https://github.com/unjs/unplugin)). While we tried to keep changes to v1 of the webpack plugin minimal, a adjustments are nevertheless necessary: |
16 | 8 |
|
17 | 9 | ### Initialization and Required Values |
18 | 10 |
|
19 | 11 | Previously, to use the plugin, you had to create a new class of the `SentryCLIPlugin` class. |
20 | | -In version 2, you simply need to call a function and pass the initialization options to it. |
21 | | -Note that in this new version, more options are now explicitly required. Here's an example: |
| 12 | +In version 2, you simply need to call a function and pass the initialization options to it: |
22 | 13 |
|
23 | 14 | ```js |
24 | | -// old config + environment variables were set for authToken, org and project |
| 15 | +// old initialization: |
25 | 16 | new SentryCliPlugin({ |
26 | 17 | include: "./dist", |
27 | 18 | }); |
28 | 19 |
|
29 | | -// new config (you can still use env variables but you need to set them explicitly): |
| 20 | +// new initialization: |
30 | 21 | sentryWebpackPlugin({ |
31 | 22 | include: "./dist", |
32 | | - authToken: process.env.SENTRY_AUTH_TOKEN, |
33 | | - org: process.env.SENTRY_ORG, |
34 | | - project: process.env.SENTRY_PROJECT, |
35 | 23 | }); |
36 | 24 | ``` |
37 | 25 |
|
38 | | -### Removal of `configFile` option |
39 | | - |
40 | | -Previously, you could set the `configFile` option when initializing the plugin to point `sentry-cli` to its `.sentryclirc` config. |
41 | | -Because `sentry-cli` is no longer part of the plugin, this is option was removed. |
42 | | -If you previously used this option, make sure to specify all required options when intializing the plugin (see [Initialization and Required Values](#initialization-and-required-values)). |
43 | | - |
44 | | -### Removal of globbing |
45 | | - |
46 | | -Previously it was possible to glob for files to include in the sourcemap upload (e.g. `include: "./my-build-dir/**"`). |
47 | | -In version 2 we removed this functionality because it lead to intransparent naming of release artifacts. |
48 | | - |
49 | | -Going forward, if you need similar functionality, we recommend providing folder paths in the `include` and `include.paths` options and narrowing down the matched files with the `ignore`, `ignoreFile` or `ext` options. |
50 | | -The `ignore` and `ignoreFile` options will still allow globbing patterns. |
51 | | - |
52 | 26 | ### Injecting `SENTRY_RELEASES` Map |
53 | 27 |
|
54 | 28 | Previously, the webpack plugin always injected a `SENTRY_RELEASES` variable into the global object which would map from `project@org` to the `release` value. In version 2, we made this behaviour opt-in by setting the `injectReleasesMap` option in the plugin options to `true`. |
|
0 commit comments