From b4f043da6ac296720008df8e536d4ae01efb71c4 Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Fri, 13 Dec 2024 15:26:07 +0100 Subject: [PATCH] ref(js): Add section about version alignment to Micro Frontends documentation #12023 --- .../common/best-practices/micro-frontends.mdx | 32 ++++++++++++++++--- 1 file changed, 27 insertions(+), 5 deletions(-) diff --git a/docs/platforms/javascript/common/best-practices/micro-frontends.mdx b/docs/platforms/javascript/common/best-practices/micro-frontends.mdx index 5b1985c1d4c4f..6094889f64ac4 100644 --- a/docs/platforms/javascript/common/best-practices/micro-frontends.mdx +++ b/docs/platforms/javascript/common/best-practices/micro-frontends.mdx @@ -21,11 +21,14 @@ keywords: "module metadata", ] --- + -To ensure the Sentry JavaScript SDK works with your micro frontends, make sure all micro frontends that import from a `@sentry/*` package are using the same version of the Sentry SDK. + To ensure the Sentry JavaScript SDK works with your micro frontends, make sure + all micro frontends that import from a `@sentry/*` package are [using the same + version of the Sentry SDK](#sdk-version-alignment). -If your app uses micro frontends, it’s very useful to be able to track which one an error is coming from. To do this with Sentry, you can create either an automatic or a manual setup where you send events to separate Sentry projects representing each of your micro frontends. This makes it easier to see what’s going wrong and where, helping you track issues and fix them faster, especially in complex frontend architectures. +If your app uses micro frontends, it's very useful to be able to track which one an error is coming from. To do this with Sentry, you can create either an automatic or a manual setup where you send events to separate Sentry projects representing each of your micro frontends. This makes it easier to see what's going wrong and where, helping you track issues and fix them faster, especially in complex frontend architectures. Below you'll find setup instructions for both an automatic and a manual way to route errors to different Sentry projects. @@ -177,9 +180,14 @@ init({ You can then set tags/contexts on events in individual micro-frontends to decide which Sentry project to send the event to as follows: - It's important to always use a local scope when setting the tag (either as shown below or using{" "} - withScope documentation ). Using a global scope, for example, through `Sentry.setTag()` will result in all subsequent events being routed to the - same DSN regardless of where they originated. + It's important to always use a local scope when setting the tag (either as + shown below or using{" "} + + withScope documentation{" "} + + ). Using a global scope, for example, through `Sentry.setTag()` will result in + all subsequent events being routed to the same DSN regardless of where they + originated. ```typescript @@ -188,3 +196,17 @@ captureException(new Error("oh no!"), (scope) => { return scope; }); ``` + +## SDK Version Alignment + +Starting with version [8.7.0](https://github.com/getsentry/sentry-javascript/releases/tag/8.7.0), if you have multiple Sentry JavaScript SDKs on the same page, they [only interact with each other](https://github.com/getsentry/sentry-javascript/pull/12206) if they're using the same version. This prevents unwanted cross-SDK interactions, where calls or accesses to recently added or no longer existing SDK APIs would lead to errors. A classic example for this are browser extensions or 3rd party scripts using Sentry when the host app also uses Sentry. + +However, for use cases like micro frontends, where you might _want_ SDK interaction across multiple micro frontends or child applications, you'll need to ensure that all SDKs are using the same version. +For example, if you initialize the SDK in a host or skeleton application, but make Sentry SDK calls (like `Sentry.captureException` or `Sentry.setTag`) in micro frontend child applications, you need to ensure that the SDK packages in the host and child applications are aligned to the same version. + + + +If you can't get all your micro frontends aligned on the same SDK version, you can [follow this workaround](https://github.com/getsentry/sentry-javascript/discussions/10576#discussioncomment-11446422). +However, interoperability isn't guaranteed and you could run into some unexpected behavior. + +