From b9e3d9846f7f3370419cef411c99bdc90e0813ce Mon Sep 17 00:00:00 2001 From: Luca Forstner Date: Fri, 8 Apr 2022 12:23:56 +0200 Subject: [PATCH 1/2] Add migration guide for JS SDK Starting with migration from v6 to v7 --- src/platforms/javascript/common/migration.mdx | 55 +++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 src/platforms/javascript/common/migration.mdx diff --git a/src/platforms/javascript/common/migration.mdx b/src/platforms/javascript/common/migration.mdx new file mode 100644 index 0000000000000..269db7b335859 --- /dev/null +++ b/src/platforms/javascript/common/migration.mdx @@ -0,0 +1,55 @@ +--- +title: Migration Guide +description: "Learn about how to migrate between major versions of the JavaScript SDKs." +sidebar_order: 2000 +--- + +This page will outline how to migrate your applications between major versions of the Sentry SDK from version 6 onwards. + +## From 6.x to 7.x + +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. +Below we will outline all the breaking changes you should consider when upgrading. + +### Moving To ES6 For CommonJS Files + +The JavaScript world is moving forward, and so are we. From version 7 onwards the CommonJS files in Sentry JavaScript SDK packages will use ES6. + +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. + +### Dropping Support for Node.js v6 + +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. + +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. +Running the new SDK version on Node.js v6 is therefore highly discouraged. + +### Removal Of Old Platform Integrations From `@sentry/integrations` Package + +The following classes will be removed from the `@sentry/integrations` package and can no longer be used: + +- `Angular` +- `Ember` +- `Vue` + +These classes have been superseded and were moved into their own packages, `@sentry/angular`, `@sentry/ember`, and `@sentry/vue` in a previous version. +Refer to those packages if you want to integrate Sentry into your Angular, Ember, or Vue application. + +### Restructuring Of Package Content + +Up until now, we have published our packages on npm with the following structure: + +- `build` folder contained CDN bundles +- `dist` folder contained CommonJS files and TypeScript declarations +- `esm` folder contained ESM files and TypeScript declarations + +Moving forward the JavaScript SDK packages will generally have the following structure: + +- `cjs` folder contains CommonJS files +- `esm` folder contains ESM files +- `types` folder contains TypeScript declarations + +**CDN bundles of version 7 or higher will no longer be distributed through our npm package.** +This means that most third-party CDNs like [unpkg](https://unpkg.com/) or [jsDelivr](https://www.jsdelivr.com/) will also not provide them. + +If you depend on any specific files in a Sentry JavaScript npm package, you will most likely need to update their references. From 1a531d88715939955db0603b48720e000e34ec22 Mon Sep 17 00:00:00 2001 From: Luca Forstner Date: Mon, 11 Apr 2022 10:36:38 +0200 Subject: [PATCH 2/2] Add general API changes to JS v7 migration guide --- src/platforms/javascript/common/migration.mdx | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/src/platforms/javascript/common/migration.mdx b/src/platforms/javascript/common/migration.mdx index 269db7b335859..3a7bb568129c0 100644 --- a/src/platforms/javascript/common/migration.mdx +++ b/src/platforms/javascript/common/migration.mdx @@ -53,3 +53,15 @@ Moving forward the JavaScript SDK packages will generally have the following str This means that most third-party CDNs like [unpkg](https://unpkg.com/) or [jsDelivr](https://www.jsdelivr.com/) will also not provide them. If you depend on any specific files in a Sentry JavaScript npm package, you will most likely need to update their references. + +### General API Changes + +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: + +- Remove support for deprecated `@sentry/apm` package. `@sentry/tracing` should be used instead. +- Remove `API` class from `@sentry/core`. `APIDetails` should be used instead. +- Remove `user` field from DSN. `publicKey` should be used instead. +- 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. +- Gatsby SDK: Remove `Sentry` from `window` object. +- Remove `getActiveDomain` method and `DomainAsCarrier` type from `@sentry/hub`. +- Rename `registerRequestInstrumentation` to `instrumentOutgoingRequests` in `@sentry/tracing`.