From 2db02b1352b992e9f84b035d90e16dc5f214f4f6 Mon Sep 17 00:00:00 2001 From: Abdelrahman Awad Date: Fri, 14 Nov 2025 13:48:31 +0200 Subject: [PATCH 1/8] feat: add vercel specific microfrontends guide --- .../nextjs/best-practices/micro-frontends.mdx | 39 +++++++++++++++++++ .../javascript/guides/nextjs/index.mdx | 1 + 2 files changed, 40 insertions(+) create mode 100644 docs/platforms/javascript/guides/nextjs/best-practices/micro-frontends.mdx diff --git a/docs/platforms/javascript/guides/nextjs/best-practices/micro-frontends.mdx b/docs/platforms/javascript/guides/nextjs/best-practices/micro-frontends.mdx new file mode 100644 index 0000000000000..1255e97dbb919 --- /dev/null +++ b/docs/platforms/javascript/guides/nextjs/best-practices/micro-frontends.mdx @@ -0,0 +1,39 @@ +--- +title: Micro Frontends +description: "Learn how to add Sentry instrumentation to your Vercel's micro frontend projects." +--- + + + +You also need a [micro frontends project](https://vercel.com/docs/microfrontends) deployed to Vercel. + +## Overview + +There are many ways to use micro frontends. You can split your application into smaller projects, each managed by a different team. Each micro frontend project can be either a separate application with its own tech stack and UI, or it can contribute a piece of functionality or content to a host application. + +- **Multi-zone applications**: Multiple independent projects, where each is its own application with its own UI and tech stack. +- **Module Federation**: A host application that pulls in other applications as dependencies or shares components and functionality with other applications. + +## Multi-zone Applications + +Multi-zone applications allow you to slice a large application into smaller, more manageable projects. Each project is its own application with its own UI and tech stack. For example, you could use Next.js for one project, SvelteKit for another, and React for a third. + +To set up Sentry for a multi-zone application, set up Sentry for each project individually by following the installation instructions for each framework: + +- **[Next.js](/platforms/javascript/guides/nextjs/)** +- **[React Router](/platforms/javascript/guides/react/)** +- **[SvelteKit](/platforms/javascript/guides/sveltekit/)** + + + We recommend using a different DSN for each project. This makes it easier to + identify which project errors are coming from, helping you track issues and + fix them faster in complex frontend architectures. + + +## Module Federation + +For micro frontends using module federation (where a host application pulls in other applications as dependencies), see the [JavaScript Micro Frontends documentation](/platforms/javascript/best-practices/micro-frontends/), which covers: + +- Automatically routing errors to different projects using `ModuleMetadata` and `makeMultiplexedTransport` +- Manually routing errors to different projects +- SDK version alignment across micro frontends diff --git a/docs/platforms/javascript/guides/nextjs/index.mdx b/docs/platforms/javascript/guides/nextjs/index.mdx index 08878b10dbb60..226a78c445e8b 100644 --- a/docs/platforms/javascript/guides/nextjs/index.mdx +++ b/docs/platforms/javascript/guides/nextjs/index.mdx @@ -217,6 +217,7 @@ Our next recommended steps for you are: - Learn how to [manually capture errors](/platforms/javascript/guides/nextjs/usage/) - Continue to [customize your configuration](/platforms/javascript/guides/nextjs/configuration/) - Get familiar with [Sentry's product features](/product) like tracing, insights, and alerts +- Learn how to [set up Sentry for Vercel's microfrontends](/platforms/javascript/guides/nextjs/best-practices/micro-frontends/) - Learn more about our [Vercel integration](/organization/integrations/deployment/vercel/) From dc50d671372e7e9eb4dd75c25a335f70c80f363e Mon Sep 17 00:00:00 2001 From: Abdelrahman Awad Date: Mon, 24 Nov 2025 10:26:25 +0200 Subject: [PATCH 2/8] docs: include the vercel multi-zone app guide in the common microfrontend guide --- .../common/best-practices/micro-frontends.mdx | 33 +++++++++++++--- .../nextjs/best-practices/micro-frontends.mdx | 39 ------------------- 2 files changed, 28 insertions(+), 44 deletions(-) delete mode 100644 docs/platforms/javascript/guides/nextjs/best-practices/micro-frontends.mdx diff --git a/docs/platforms/javascript/common/best-practices/micro-frontends.mdx b/docs/platforms/javascript/common/best-practices/micro-frontends.mdx index b6ac8459f2dfb..d2af9f14a3ddb 100644 --- a/docs/platforms/javascript/common/best-practices/micro-frontends.mdx +++ b/docs/platforms/javascript/common/best-practices/micro-frontends.mdx @@ -33,9 +33,28 @@ If your app uses micro frontends, it's very useful to be able to track which one Below you'll find setup instructions for both an automatic and a manual way to route errors to different Sentry projects. + + +## Vercel Multi-Zone Micro Frontends + +Multi-zone applications allow you to slice a large application into smaller, more manageable projects. Each project is its own application with its own UI and tech stack. For example, you could use Next.js for one project, SvelteKit for another, and React for a third. + +To set up Sentry for a multi-zone application, set up Sentry for each project individually by following the installation instructions for each framework: + +- **[Next.js](/platforms/javascript/guides/nextjs/)** +- **[React Router](/platforms/javascript/guides/react/)** +- **[SvelteKit](/platforms/javascript/guides/sveltekit/)** + +We recommend using a different DSN for each project. This makes it easier to +identify which project errors are coming from, helping you track issues and +fix them faster in complex frontend architectures. + + + - In all cases `Sentry.init()` must never be called more than once, doing so - will result in undefined behavior. + With the exception of Vercel Multi-Zone Micro Frontends, you should call + `Sentry.init()` only once in your application. Initializing Sentry multiple + times can lead to unexpected behavior. ## Automatically Route Errors to Different Projects @@ -75,7 +94,8 @@ module.exports = { ``` - **Replace `__MODULE_DSN__` with your actual Sentry project DSN.** You can find your DSN in your Sentry project settings under Client Keys (DSN). + **Replace `__MODULE_DSN__` with your actual Sentry project DSN.** You can find + your DSN in your Sentry project settings under Client Keys (DSN). Once metadata has been injected into modules, the `moduleMetadataIntegration` @@ -203,7 +223,9 @@ init({ ``` - **Replace `__DEFAULT_DSN__` with your actual Sentry project DSN.** This should be the DSN for your default/fallback Sentry project. You can find your DSN in your Sentry project settings under Client Keys (DSN). + **Replace `__DEFAULT_DSN__` with your actual Sentry project DSN.** This should + be the DSN for your default/fallback Sentry project. You can find your DSN in + your Sentry project settings under Client Keys (DSN). Once this is set up, errors - both handled and unhandled - will be automatically routed to the right project. @@ -257,7 +279,8 @@ init({ - Replace `__CART_DSN__` with the DSN for your cart micro frontend's Sentry project - Replace `__GALLERY_DSN__` with the DSN for your gallery micro frontend's Sentry project - You can find your DSNs in each Sentry project's settings under Client Keys (DSN). +You can find your DSNs in each Sentry project's settings under Client Keys (DSN). + You can then set tags/contexts on events in individual micro-frontends to decide which Sentry project to send the event to as follows: diff --git a/docs/platforms/javascript/guides/nextjs/best-practices/micro-frontends.mdx b/docs/platforms/javascript/guides/nextjs/best-practices/micro-frontends.mdx deleted file mode 100644 index 1255e97dbb919..0000000000000 --- a/docs/platforms/javascript/guides/nextjs/best-practices/micro-frontends.mdx +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Micro Frontends -description: "Learn how to add Sentry instrumentation to your Vercel's micro frontend projects." ---- - - - -You also need a [micro frontends project](https://vercel.com/docs/microfrontends) deployed to Vercel. - -## Overview - -There are many ways to use micro frontends. You can split your application into smaller projects, each managed by a different team. Each micro frontend project can be either a separate application with its own tech stack and UI, or it can contribute a piece of functionality or content to a host application. - -- **Multi-zone applications**: Multiple independent projects, where each is its own application with its own UI and tech stack. -- **Module Federation**: A host application that pulls in other applications as dependencies or shares components and functionality with other applications. - -## Multi-zone Applications - -Multi-zone applications allow you to slice a large application into smaller, more manageable projects. Each project is its own application with its own UI and tech stack. For example, you could use Next.js for one project, SvelteKit for another, and React for a third. - -To set up Sentry for a multi-zone application, set up Sentry for each project individually by following the installation instructions for each framework: - -- **[Next.js](/platforms/javascript/guides/nextjs/)** -- **[React Router](/platforms/javascript/guides/react/)** -- **[SvelteKit](/platforms/javascript/guides/sveltekit/)** - - - We recommend using a different DSN for each project. This makes it easier to - identify which project errors are coming from, helping you track issues and - fix them faster in complex frontend architectures. - - -## Module Federation - -For micro frontends using module federation (where a host application pulls in other applications as dependencies), see the [JavaScript Micro Frontends documentation](/platforms/javascript/best-practices/micro-frontends/), which covers: - -- Automatically routing errors to different projects using `ModuleMetadata` and `makeMultiplexedTransport` -- Manually routing errors to different projects -- SDK version alignment across micro frontends From 5e2ed27b1f19998929ac84351d454e536f5a2ab2 Mon Sep 17 00:00:00 2001 From: Abdelrahman Awad Date: Mon, 24 Nov 2025 10:31:10 +0200 Subject: [PATCH 3/8] fix: keep old alert for non nextjs pages --- .../common/best-practices/micro-frontends.mdx | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/docs/platforms/javascript/common/best-practices/micro-frontends.mdx b/docs/platforms/javascript/common/best-practices/micro-frontends.mdx index d2af9f14a3ddb..08b5f4f08c3ac 100644 --- a/docs/platforms/javascript/common/best-practices/micro-frontends.mdx +++ b/docs/platforms/javascript/common/best-practices/micro-frontends.mdx @@ -49,14 +49,23 @@ We recommend using a different DSN for each project. This makes it easier to identify which project errors are coming from, helping you track issues and fix them faster in complex frontend architectures. - - With the exception of Vercel Multi-Zone Micro Frontends, you should call `Sentry.init()` only once in your application. Initializing Sentry multiple times can lead to unexpected behavior. + + + + + + In all cases `Sentry.init()` must never be called more than once, doing so + will result in undefined behavior. + + + + ## Automatically Route Errors to Different Projects `ModuleMetadata` and `makeMultiplexedTransport` can be used together to automatically route events to specific Sentry projects that represent your micro frontend services. Events will be routed once the service where the error occurred has been identified, ensuring errors are tracked in the correct project. From e28cab76d6619c3c3d4fefbd4032e2bc6a49ea91 Mon Sep 17 00:00:00 2001 From: Abdelrahman Awad Date: Mon, 24 Nov 2025 10:35:42 +0200 Subject: [PATCH 4/8] docs: wording --- .../javascript/common/best-practices/micro-frontends.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/platforms/javascript/common/best-practices/micro-frontends.mdx b/docs/platforms/javascript/common/best-practices/micro-frontends.mdx index 08b5f4f08c3ac..d4ebc94bc1ea1 100644 --- a/docs/platforms/javascript/common/best-practices/micro-frontends.mdx +++ b/docs/platforms/javascript/common/best-practices/micro-frontends.mdx @@ -37,9 +37,9 @@ Below you'll find setup instructions for both an automatic and a manual way to r ## Vercel Multi-Zone Micro Frontends -Multi-zone applications allow you to slice a large application into smaller, more manageable projects. Each project is its own application with its own UI and tech stack. For example, you could use Next.js for one project, SvelteKit for another, and React for a third. +Vercel's Multi-zone applications let you slice a large app into smaller, independently managed projects. Each project operates as its own application, with its own UI and tech stack. For example, you might use Next.js for one project, SvelteKit for another, and React for a third. -To set up Sentry for a multi-zone application, set up Sentry for each project individually by following the installation instructions for each framework: +To set up Sentry in a multi-zone setup, configure Sentry separately within each project. Follow the installation steps for the framework each project uses. Here are a few examples: - **[Next.js](/platforms/javascript/guides/nextjs/)** - **[React Router](/platforms/javascript/guides/react/)** From e74193b4374d0f462748d17ecdb98a7bde79366c Mon Sep 17 00:00:00 2001 From: Abdelrahman Awad Date: Mon, 24 Nov 2025 11:55:11 +0100 Subject: [PATCH 5/8] fix: consistent wording Co-authored-by: Sarah Mischinger --- docs/platforms/javascript/guides/nextjs/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/javascript/guides/nextjs/index.mdx b/docs/platforms/javascript/guides/nextjs/index.mdx index 226a78c445e8b..ecbbfc013d52b 100644 --- a/docs/platforms/javascript/guides/nextjs/index.mdx +++ b/docs/platforms/javascript/guides/nextjs/index.mdx @@ -217,7 +217,7 @@ Our next recommended steps for you are: - Learn how to [manually capture errors](/platforms/javascript/guides/nextjs/usage/) - Continue to [customize your configuration](/platforms/javascript/guides/nextjs/configuration/) - Get familiar with [Sentry's product features](/product) like tracing, insights, and alerts -- Learn how to [set up Sentry for Vercel's microfrontends](/platforms/javascript/guides/nextjs/best-practices/micro-frontends/) +- Learn how to [set up Sentry for Vercel's micro frontends](/platforms/javascript/guides/nextjs/best-practices/micro-frontends/) - Learn more about our [Vercel integration](/organization/integrations/deployment/vercel/) From cb40c9f89620e6e2688372ae90af34c7d23b1eab Mon Sep 17 00:00:00 2001 From: Abdelrahman Awad Date: Mon, 24 Nov 2025 11:55:35 +0100 Subject: [PATCH 6/8] fix: capitalization and wording Co-authored-by: Sarah Mischinger --- .../javascript/common/best-practices/micro-frontends.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/javascript/common/best-practices/micro-frontends.mdx b/docs/platforms/javascript/common/best-practices/micro-frontends.mdx index d4ebc94bc1ea1..095329803f414 100644 --- a/docs/platforms/javascript/common/best-practices/micro-frontends.mdx +++ b/docs/platforms/javascript/common/best-practices/micro-frontends.mdx @@ -50,7 +50,7 @@ identify which project errors are coming from, helping you track issues and fix them faster in complex frontend architectures. - With the exception of Vercel Multi-Zone Micro Frontends, you should call + With the exception of Vercel multi-zone micro frontends, you should call `Sentry.init()` only once in your application. Initializing Sentry multiple times can lead to unexpected behavior. From 0040a52ee5ade77e62e76462cb712c6d6b9e7202 Mon Sep 17 00:00:00 2001 From: Abdelrahman Awad Date: Mon, 24 Nov 2025 11:56:03 +0100 Subject: [PATCH 7/8] fix: link text to react sdk Co-authored-by: Sarah Mischinger --- .../javascript/common/best-practices/micro-frontends.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/javascript/common/best-practices/micro-frontends.mdx b/docs/platforms/javascript/common/best-practices/micro-frontends.mdx index 095329803f414..48ce8559f46ca 100644 --- a/docs/platforms/javascript/common/best-practices/micro-frontends.mdx +++ b/docs/platforms/javascript/common/best-practices/micro-frontends.mdx @@ -42,7 +42,7 @@ Vercel's Multi-zone applications let you slice a large app into smaller, indepen To set up Sentry in a multi-zone setup, configure Sentry separately within each project. Follow the installation steps for the framework each project uses. Here are a few examples: - **[Next.js](/platforms/javascript/guides/nextjs/)** -- **[React Router](/platforms/javascript/guides/react/)** +- **[React](/platforms/javascript/guides/react/)** - **[SvelteKit](/platforms/javascript/guides/sveltekit/)** We recommend using a different DSN for each project. This makes it easier to From 572ace26657d1356cfee0093c5f1c3c31eb386e6 Mon Sep 17 00:00:00 2001 From: Abdelrahman Awad Date: Mon, 24 Nov 2025 11:56:19 +0100 Subject: [PATCH 8/8] fix: capitalization Co-authored-by: Sarah Mischinger --- .../javascript/common/best-practices/micro-frontends.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/javascript/common/best-practices/micro-frontends.mdx b/docs/platforms/javascript/common/best-practices/micro-frontends.mdx index 48ce8559f46ca..489e107e1c0e1 100644 --- a/docs/platforms/javascript/common/best-practices/micro-frontends.mdx +++ b/docs/platforms/javascript/common/best-practices/micro-frontends.mdx @@ -37,7 +37,7 @@ Below you'll find setup instructions for both an automatic and a manual way to r ## Vercel Multi-Zone Micro Frontends -Vercel's Multi-zone applications let you slice a large app into smaller, independently managed projects. Each project operates as its own application, with its own UI and tech stack. For example, you might use Next.js for one project, SvelteKit for another, and React for a third. +Vercel's multi-zone applications let you slice a large app into smaller, independently managed projects. Each project operates as its own application, with its own UI and tech stack. For example, you might use Next.js for one project, SvelteKit for another, and React for a third. To set up Sentry in a multi-zone setup, configure Sentry separately within each project. Follow the installation steps for the framework each project uses. Here are a few examples: