|
| 1 | +## Upgrading from 6.x to 7.x |
| 2 | + |
| 3 | +The main goal of version 7 is to reduce bundle size. This version is breaking because we removed deprecated APIs, upgraded our build tooling, and restructured npm package contents. |
| 4 | +Below we will outline all the breaking changes you should consider when upgrading. |
| 5 | + |
| 6 | +### Dropping Support for Node.js v6 |
| 7 | + |
| 8 | +Node.js version 6 has reached end of life in April 2019. For Sentry JavaScript SDK version 7, we will no longer be supporting version 6 of Node.js. |
| 9 | + |
| 10 | +As far as SDK development goes, dropping support means no longer running integration tests for Node.js version 6, and also no longer handling edge cases specific to version 6. |
| 11 | +Running the new SDK version on Node.js v6 is therefore highly discouraged. |
| 12 | + |
| 13 | +### Removal Of Old Platform Integrations From `@sentry/integrations` Package |
| 14 | + |
| 15 | +The following classes will be removed from the `@sentry/integrations` package and can no longer be used: |
| 16 | + |
| 17 | +- `Angular` |
| 18 | +- `Ember` |
| 19 | +- `Vue` |
| 20 | + |
| 21 | +These classes have been superseded and were moved into their own packages, `@sentry/angular`, `@sentry/ember`, and `@sentry/vue` in a previous version. |
| 22 | +Refer to those packages if you want to integrate Sentry into your Angular, Ember, or Vue application. |
| 23 | + |
| 24 | +### Moving To ES6 For CommonJS Files |
| 25 | + |
| 26 | +From version 7 onwards, the CommonJS files in Sentry JavaScript SDK packages will use ES6. |
| 27 | + |
| 28 | +If you need to support Internet Explorer 11 or old Node.js versions, we recommend using a preprocessing tool like [Babel](https://babeljs.io/) to convert Sentry packages to ES5. |
| 29 | + |
| 30 | +### Renaming Of CDN Bundles |
| 31 | + |
| 32 | +CDN bundles will be ES6 by default. Files that followed the naming scheme `bundle.es6.min.js` were renamed to `bundle.min.js` and any bundles using ES5 (files without `.es6`) turned into `bundle.es5.min.js`. |
| 33 | + |
| 34 | +See our [docs on CDN bundles](https://docs.sentry.io/platforms/javascript/install/cdn/) for more information. |
| 35 | + |
| 36 | +### Restructuring Of Package Content |
| 37 | + |
| 38 | +Up until v6.x, we have published our packages on npm with the following structure: |
| 39 | + |
| 40 | +- `build` folder contained CDN bundles |
| 41 | +- `dist` folder contained CommonJS files and TypeScript declarations |
| 42 | +- `esm` folder contained ESM files and TypeScript declarations |
| 43 | + |
| 44 | +Moving forward the JavaScript SDK packages will generally have the following structure: |
| 45 | + |
| 46 | +- `cjs` folder contains CommonJS files |
| 47 | +- `esm` folder contains ESM files |
| 48 | +- `types` folder contains TypeScript declarations |
| 49 | + |
| 50 | +**CDN bundles of version 7 or higher will no longer be distributed through our npm package.** |
| 51 | +This means that most third-party CDNs like [unpkg](https://unpkg.com/) or [jsDelivr](https://www.jsdelivr.com/) will also not provide them. |
| 52 | + |
| 53 | +If you depend on any specific files in a Sentry JavaScript npm package, you will most likely need to update their references. |
| 54 | +For example, imports on `@sentry/browser/dist/client` will become `@sentry/browser/cjs/client`. |
| 55 | +However, directly importing from specific files is discouraged. |
| 56 | + |
| 57 | +### Removing the `API` class from `@sentry/core` |
| 58 | + |
| 59 | +The internal `API` class was removed in favor of the `initAPIDetails` function and the `APIDetails` type. More details can be found in the [PR that deprecated this class](https://github.com/getsentry/sentry-javascript/pull/4281). To migrate, see the following example. |
| 60 | + |
| 61 | +```js |
| 62 | +// New in v7: |
| 63 | +import { |
| 64 | + initAPIDetails, |
| 65 | + getEnvelopeEndpointWithUrlEncodedAuth, |
| 66 | + getStoreEndpointWithUrlEncodedAuth, |
| 67 | +} from '@sentry/core'; |
| 68 | + |
| 69 | +const dsn = initAPIDetails(dsn, metadata, tunnel); |
| 70 | +const dsn = api.dsn; |
| 71 | +const storeEndpoint = getEnvelopeEndpointWithUrlEncodedAuth(api.dsn, api.tunnel); |
| 72 | +const envelopeEndpoint = getStoreEndpointWithUrlEncodedAuth(api.dsn); |
| 73 | + |
| 74 | +// Before: |
| 75 | +import { API } from '@sentry/core'; |
| 76 | + |
| 77 | +const api = new API(dsn, metadata, tunnel); |
| 78 | +const dsn = api.getDsn(); |
| 79 | +const storeEndpoint = api.getStoreEndpointWithUrlEncodedAuth(); |
| 80 | +const envelopeEndpoint = api.getEnvelopeEndpointWithUrlEncodedAuth(); |
| 81 | +``` |
| 82 | + |
| 83 | +### General API Changes |
| 84 | + |
| 85 | +For our efforts to reduce bundle size of the SDK we had to remove and refactor parts of the package which introduced a few changes to the API: |
| 86 | + |
| 87 | +- Remove support for deprecated `@sentry/apm` package. `@sentry/tracing` should be used instead. |
| 88 | +- Remove deprecated `user` field from DSN. `publicKey` should be used instead. |
| 89 | +- Remove deprecated `whitelistUrls` and `blacklistUrls` options from `Sentry.init`. They have been superseded by `allowUrls` and `denyUrls` specifically. See [our docs page on inclusive language](https://develop.sentry.dev/inclusion/) for more details. |
| 90 | +- Gatsby SDK: Remove `Sentry` from `window` object. |
| 91 | +- Remove deprecated `Status`, `SessionStatus`, and `RequestSessionStatus` enums. These were only part of an internal API. If you are using these enums, we encourage you to to look at [b177690d](https://github.com/getsentry/sentry-javascript/commit/b177690d89640aef2587039113c614672c07d2be), [5fc3147d](https://github.com/getsentry/sentry-javascript/commit/5fc3147dfaaf1a856d5923e4ba409479e87273be), and [f99bdd16](https://github.com/getsentry/sentry-javascript/commit/f99bdd16539bf6fac14eccf1a974a4988d586b28) to to see the changes we've made to our code as result. We generally recommend using string literals instead of the removed enums. |
| 92 | +- Remove deprecated `getActiveDomain` method and `DomainAsCarrier` type from `@sentry/hub`. |
| 93 | +- Rename `registerRequestInstrumentation` to `instrumentOutgoingRequests` in `@sentry/tracing`. |
| 94 | + |
1 | 95 | # Upgrading from 6.17.x to 6.18.0 |
2 | 96 |
|
3 | 97 | Version 6.18.0 deprecates the `frameContextLines` top-level option for the Node SDK. This option will be removed in an upcoming major version. To migrate off of the top-level option, pass it instead to the new `ContextLines` integration. |
|
0 commit comments