From 4f99b00d65d3f6328ac7bf39d5a64e743033d9ee Mon Sep 17 00:00:00 2001 From: Rutchanai <122603999+rutchanai@users.noreply.github.com> Date: Wed, 9 Jul 2025 11:34:33 +0700 Subject: [PATCH 1/4] docs(next): correct typo in recommended badge (#3892) --- apps/website-new/docs/en/practice/frameworks/next/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/website-new/docs/en/practice/frameworks/next/index.mdx b/apps/website-new/docs/en/practice/frameworks/next/index.mdx index 3284a74915..347f1bd2eb 100644 --- a/apps/website-new/docs/en/practice/frameworks/next/index.mdx +++ b/apps/website-new/docs/en/practice/frameworks/next/index.mdx @@ -18,7 +18,7 @@ Support for Next.js is ending [read more](https://github.com/module-federation/c - + # :::tip Demo Reference From 60e4df1fd6c0f7f22aaa5346faed8e275e787558 Mon Sep 17 00:00:00 2001 From: Zack Jackson <25274700+ScriptedAlchemy@users.noreply.github.com> Date: Wed, 9 Jul 2025 10:05:51 -0700 Subject: [PATCH 2/4] fix: set files on runtime-tools pkg (#3889) Co-authored-by: Cursor Agent --- .changeset/tidy-foxes-fix.md | 8 ++++++++ packages/runtime-tools/package.json | 4 ++++ 2 files changed, 12 insertions(+) create mode 100644 .changeset/tidy-foxes-fix.md diff --git a/.changeset/tidy-foxes-fix.md b/.changeset/tidy-foxes-fix.md new file mode 100644 index 0000000000..82119f58f7 --- /dev/null +++ b/.changeset/tidy-foxes-fix.md @@ -0,0 +1,8 @@ +--- +"@module-federation/runtime-tools": patch +--- + +fix: add files property to package.json to exclude build config from npm publish + +Fixes #3873 where .swcrc file was being published to npm causing Jest test failures. +Only dist/ and README.md will now be included in the published package. \ No newline at end of file diff --git a/packages/runtime-tools/package.json b/packages/runtime-tools/package.json index db048feb3c..33423e0c1d 100644 --- a/packages/runtime-tools/package.json +++ b/packages/runtime-tools/package.json @@ -12,6 +12,10 @@ "url": "https://github.com/module-federation/core/", "directory": "packages/runtime-tools" }, + "files": [ + "dist/", + "README.md" + ], "publishConfig": { "access": "public" }, From 4dc2beafa39a552ecc8a1850e00b6011e18d22e5 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Fri, 11 Jul 2025 20:19:26 +0000 Subject: [PATCH 3/4] docs(nextjs-mf): add detailed sharing mechanism documentation with Mermaid diagrams --- nextjs-mf-sharing-diagram.md | 454 +++++++++++++++++++++++++++++++++++ 1 file changed, 454 insertions(+) create mode 100644 nextjs-mf-sharing-diagram.md diff --git a/nextjs-mf-sharing-diagram.md b/nextjs-mf-sharing-diagram.md new file mode 100644 index 0000000000..2c0489f4c6 --- /dev/null +++ b/nextjs-mf-sharing-diagram.md @@ -0,0 +1,454 @@ +# Next.js Module Federation Plugin Sharing Mechanism Documentation + +## Overview + +This document details the sharing mechanism in the Next.js Module Federation plugin, showing how it handles sharing between client and server environments across Next.js versions 14 and 15. + +## Architecture Flow Diagram + +```mermaid +flowchart TB + subgraph "Next.js MF Plugin Core" + Plugin[NextFederationPlugin] + Internal[internal.ts] + Fragments[next-fragments.ts] + end + + subgraph "Sharing Configuration" + DSS[DEFAULT_SHARE_SCOPE] + DSSB[DEFAULT_SHARE_SCOPE_BROWSER] + RDS[retrieveDefaultShared] + end + + subgraph "Environment Detection" + IsServer{isServer?} + ServerBuild[Server Build] + ClientBuild[Client Build] + end + + subgraph "Layer System (Next.js 15)" + RSC[React Server Components - 'rsc'] + SSR[Server Side Rendering - 'ssr'] + Client[Client/Browser - undefined layer] + ActionBrowser[Action Browser - 'action-browser'] + API[API Routes - 'api'] + Middleware[Middleware - 'middleware'] + Instrument[Instrumentation - 'instrument'] + EdgeAsset[Edge Assets - 'edge-asset'] + AppPages[App Pages Browser - 'app-pages-browser'] + end + + subgraph "Shared Modules" + React[React Modules] + NextModules[Next.js Modules] + StyledJSX[styled-jsx] + end + + subgraph "Server Sharing" + ServerShared[Server Shared Config] + ServerPlugins[applyServerPlugins] + ServerExternals[handleServerExternals] + end + + subgraph "Client Sharing" + ClientShared[Client Shared Config] + ClientPlugins[applyClientPlugins] + ChunkCorrelation[ChunkCorrelationPlugin] + InvertedContainer[InvertedContainerPlugin] + end + + Plugin --> IsServer + IsServer -->|Yes| ServerBuild + IsServer -->|No| ClientBuild + + ServerBuild --> RDS + ClientBuild --> RDS + + RDS -->|Server| DSS + RDS -->|Client| DSSB + + Internal --> DSS + Internal --> DSSB + Fragments --> RDS + + DSS --> ServerShared + DSSB --> ClientShared + + ServerShared --> ServerPlugins + ServerPlugins --> ServerExternals + + ClientShared --> ClientPlugins + ClientPlugins --> ChunkCorrelation + ClientPlugins --> InvertedContainer + + React --> DSS + React --> DSSB + NextModules --> DSS + NextModules --> DSSB + StyledJSX --> DSS + StyledJSX --> DSSB + + RSC -.->|Layer-based sharing| React + SSR -.->|Layer-based sharing| React + Client -.->|Layer-based sharing| React +``` + +## Sharing Configuration Details + +```mermaid +graph LR + subgraph "Shared Module Configuration" + subgraph "Core React Modules" + R1[react - singleton: true, requiredVersion: false, import: false] + R2[react/ - singleton: true, requiredVersion: false, import: false] + R3[react-dom - singleton: true, requiredVersion: false, import: false] + R4[react-dom/ - singleton: true, requiredVersion: false, import: false] + R5[react/jsx-runtime - singleton: true, requiredVersion: false] + R6[react/jsx-dev-runtime - singleton: true, requiredVersion: false] + end + + subgraph "Next.js Modules" + N1[next/dynamic - singleton: true, import: undefined] + N2[next/head - singleton: true, import: undefined] + N3[next/link - singleton: true, import: undefined] + N4[next/router - singleton: true, requiredVersion: false] + N5[next/image - singleton: true, import: undefined] + N6[next/script - singleton: true, import: undefined] + end + + subgraph "Styled JSX" + S1[styled-jsx - singleton: true, versioned] + S2[styled-jsx/style - singleton: true, import: false, versioned] + S3[styled-jsx/css - singleton: true, versioned] + end + end +``` + +## Environment-Specific Sharing Flow + +```mermaid +sequenceDiagram + participant Plugin as NextFederationPlugin + participant Compiler as Webpack Compiler + participant RDS as retrieveDefaultShared + participant Server as Server Environment + participant Client as Client Environment + + Plugin->>Compiler: Check environment (isServer) + + alt Server Build + Compiler->>Plugin: isServer = true + Plugin->>RDS: retrieveDefaultShared(true) + RDS->>Plugin: Return DEFAULT_SHARE_SCOPE + Plugin->>Server: Apply server-specific configuration + Server->>Server: Set import: false for Next internals + Server->>Server: Configure externals handling + Server->>Server: Add node runtime plugin + else Client Build + Compiler->>Plugin: isServer = false + Plugin->>RDS: retrieveDefaultShared(false) + RDS->>Plugin: Return DEFAULT_SHARE_SCOPE_BROWSER + Plugin->>Client: Apply client-specific configuration + Client->>Client: Set import: undefined for all modules + Client->>Client: Apply ChunkCorrelationPlugin + Client->>Client: Apply InvertedContainerPlugin + end +``` + +## Layer-Based Sharing (Next.js 15) + +### Layer Definitions Table + +| Layer Name | Key | Description | Usage | +|------------|-----|-------------|-------| +| Shared | `shared` | Shared code between client and server bundles | Common utilities | +| React Server Components | `rsc` | Server-only runtime for RSC | App Router RSC pages | +| Server Side Rendering | `ssr` | SSR layer for app directory | Server-rendered pages | +| Action Browser | `action-browser` | Browser client bundle for actions | Server actions client | +| API | `api` | API routes layer | API endpoints | +| Middleware | `middleware` | Middleware code layer | Edge middleware | +| Instrumentation | `instrument` | Instrumentation hooks | Monitoring/telemetry | +| Edge Asset | `edge-asset` | Assets on the edge | Edge-optimized assets | +| App Pages Browser | `app-pages-browser` | Browser client bundle for App | Client-side app pages | + +### Module Sharing by Environment + +| Module | Server (DEFAULT_SHARE_SCOPE) | Client (DEFAULT_SHARE_SCOPE_BROWSER) | Notes | +|--------|------------------------------|--------------------------------------|-------| +| react | `import: false` | `import: undefined` | External on server | +| react-dom | `import: false` | `import: undefined` | External on server | +| next/router | `import: undefined` | `import: undefined` | Bundled in both | +| next/link | `import: undefined` | `import: undefined` | Bundled in both | +| next/dynamic | `import: undefined` | `import: undefined` | Bundled in both | +| styled-jsx | `import: undefined` | `import: undefined` | Versioned sharing | + +### Layer-Based Sharing Configuration (Currently Commented Out) + +```javascript +// Example of layer-based sharing for React +const reactShares = { + 'react-rsc': { + singleton: true, + requiredVersion: false, + import: undefined, + layer: 'rsc', + issuerLayer: 'rsc' + }, + 'react-ssr': { + singleton: true, + requiredVersion: false, + import: undefined, + layer: 'ssr', + issuerLayer: 'ssr' + }, + 'react': { + singleton: true, + requiredVersion: false, + import: false, + layer: undefined, + issuerLayer: undefined + } +} +``` + +## Key Differences Between Next.js 14 and 15 + +| Aspect | Next.js 14 | Next.js 15 | Notes | +|--------|------------|------------|-------| +| Sharing Mechanism | Traditional sharing | Layer-aware sharing (prepared) | Same core implementation | +| External Handling | Standard externals | Dynamic externals detection | Improved in 8.7.1 | +| Layer Support | Basic layers | Full layer system | RSC, SSR, etc. | +| Runtime Plugins | Standard plugins | Same + Universe tracking | Enhanced tracking | + +## Plugin Application Flow + +```mermaid +stateDiagram-v2 + [*] --> Initialize: NextFederationPlugin + Initialize --> ValidateOptions + ValidateOptions --> DetectEnvironment + + DetectEnvironment --> ServerConfig: isServer = true + DetectEnvironment --> ClientConfig: isServer = false + + ServerConfig --> RetrieveServerShared + RetrieveServerShared --> ApplyServerPlugins + ApplyServerPlugins --> ConfigureExternals + ConfigureExternals --> AddNodeRuntime + AddNodeRuntime --> ApplyModuleFederation + + ClientConfig --> RetrieveClientShared + RetrieveClientShared --> ApplyClientPlugins + ApplyClientPlugins --> SetLibraryWindow + SetLibraryWindow --> AddChunkCorrelation + AddChunkCorrelation --> AddInvertedContainer + AddInvertedContainer --> ApplyModuleFederation + + ApplyModuleFederation --> ConfigureLayers + ConfigureLayers --> [*] +``` + +## Runtime Plugin Sharing Resolution + +```mermaid +flowchart TD + Start[resolveShare Called] --> CheckPkg{Is React/Next pkg?} + CheckPkg -->|No| Return[Return unchanged] + CheckPkg -->|Yes| GetHost[Get Federation Host] + GetHost --> CheckHost{Host exists?} + CheckHost -->|No| Return + CheckHost -->|Yes| CheckShared{Has shared config?} + CheckShared -->|No| Return + CheckShared -->|Yes| SetResolver[Set custom resolver] + SetResolver --> UpdateScope[Update share scope map] + UpdateScope --> End[Return modified args] +``` + +## Summary + +The Next.js Module Federation plugin uses a sophisticated sharing mechanism that: + +1. **Maintains consistency** across Next.js versions 14 and 15 +2. **Differentiates** between server and client environments +3. **Prepares** for layer-based sharing in Next.js 15 (currently commented out) +4. **Handles** React and Next.js internals specially to ensure proper module resolution +5. **Uses** runtime plugins to dynamically resolve shared modules + +The main distinction is not between Next.js versions but between server and client builds, with server builds treating React/Next internals as external modules (`import: false`) while client builds bundle them (`import: undefined`). + +## Detailed Correlation: Next.js 14 vs 15 Sharing Internals + +```mermaid +graph TB + subgraph "Next.js 14 & 15 Common Core" + subgraph "internal.ts (Shared by both versions)" + DS14[DEFAULT_SHARE_SCOPE] + DSB14[DEFAULT_SHARE_SCOPE_BROWSER] + subgraph "Commented Layer Config" + CLS[createSharedConfig] + RSH[reactShares - Layer-based] + RDSH[reactDomShares - Layer-based] + NSH[nextNavigationShares - Layer-based] + end + end + + subgraph "next-fragments.ts" + RDS14[retrieveDefaultShared function] + end + end + + subgraph "Next.js 14 Implementation" + N14S[Server Build] + N14C[Client Build] + N14T[Traditional Sharing] + end + + subgraph "Next.js 15 Implementation" + N15S[Server Build] + N15C[Client Build] + N15T[Traditional Sharing Active] + N15L[Layer Sharing Ready] + end + + DS14 --> N14S + DSB14 --> N14C + DS14 --> N15S + DSB14 --> N15C + + RDS14 --> N14T + RDS14 --> N15T + + CLS -.->|Prepared but unused| N15L + + N14S --> |Uses| DS14 + N14C --> |Uses| DSB14 + N15S --> |Uses| DS14 + N15C --> |Uses| DSB14 + + style N15L fill:#f9f,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5 +``` + +## Sharing Configuration Transformation + +### Server Environment (Both Next.js 14 & 15) + +```mermaid +graph LR + subgraph "Input: DEFAULT_SHARE_SCOPE" + I1[react: import: false] + I2[react-dom: import: false] + I3[next/router: import: undefined] + I4[styled-jsx: import: undefined] + end + + subgraph "Server Processing" + SP1[handleServerExternals] + SP2[Check if module in shared] + SP3[Keep as external if Next/React] + SP4[Bundle if in shared config] + end + + subgraph "Output: Server Bundle" + O1[react: External - from Next.js] + O2[react-dom: External - from Next.js] + O3[next/router: Bundled] + O4[styled-jsx: Bundled with version] + end + + I1 --> SP1 --> O1 + I2 --> SP1 --> O2 + I3 --> SP2 --> O3 + I4 --> SP4 --> O4 +``` + +### Client Environment (Both Next.js 14 & 15) + +```mermaid +graph LR + subgraph "Input: DEFAULT_SHARE_SCOPE_BROWSER" + CI1[react: import: undefined] + CI2[react-dom: import: undefined] + CI3[next/router: import: undefined] + CI4[styled-jsx: import: undefined] + end + + subgraph "Client Processing" + CP1[applyClientPlugins] + CP2[All modules bundled] + CP3[ChunkCorrelationPlugin] + CP4[InvertedContainerPlugin] + end + + subgraph "Output: Client Bundle" + CO1[react: Bundled + Shared] + CO2[react-dom: Bundled + Shared] + CO3[next/router: Bundled + Shared] + CO4[styled-jsx: Bundled + Shared] + end + + CI1 --> CP1 --> CO1 + CI2 --> CP1 --> CO2 + CI3 --> CP2 --> CO3 + CI4 --> CP2 --> CO4 + + CP1 --> CP3 + CP1 --> CP4 +``` + +## Future Layer-Based Sharing (Next.js 15 Ready) + +```mermaid +graph TD + subgraph "Layer-Based Module Resolution" + subgraph "React Module Variants" + R_RSC[react-rsc
Layer: rsc] + R_SSR[react-ssr
Layer: ssr] + R_Client[react
Layer: undefined] + end + + subgraph "Import Context" + RSC_Page[RSC Page Import] + SSR_Page[SSR Page Import] + Client_Comp[Client Component Import] + end + + subgraph "Resolution" + Resolver{Layer Matcher} + RSC_Bundle[Use react-rsc variant] + SSR_Bundle[Use react-ssr variant] + Client_Bundle[Use standard react] + end + end + + RSC_Page --> Resolver + SSR_Page --> Resolver + Client_Comp --> Resolver + + Resolver -->|issuerLayer: rsc| RSC_Bundle + Resolver -->|issuerLayer: ssr| SSR_Bundle + Resolver -->|issuerLayer: undefined| Client_Bundle + + R_RSC -.-> RSC_Bundle + R_SSR -.-> SSR_Bundle + R_Client -.-> Client_Bundle +``` + +## Complete Sharing Matrix + +| Module | Next.js 14 Server | Next.js 14 Client | Next.js 15 Server | Next.js 15 Client | Layer Support (15) | +|--------|-------------------|-------------------|-------------------|-------------------|--------------------| +| react | External (`import: false`) | Bundled (`import: undefined`) | External (`import: false`) | Bundled (`import: undefined`) | RSC, SSR, Client layers ready | +| react-dom | External (`import: false`) | Bundled (`import: undefined`) | External (`import: false`) | Bundled (`import: undefined`) | RSC, SSR, Client layers ready | +| react/jsx-runtime | External | Bundled | External | Bundled | Navigation layers ready | +| next/router | Bundled | Bundled | Bundled | Bundled | No layer config | +| next/link | Bundled | Bundled | Bundled | Bundled | No layer config | +| next/navigation | N/A | N/A | Bundled | Bundled | RSC, SSR layers ready | +| styled-jsx | Bundled + Versioned | Bundled + Versioned | Bundled + Versioned | Bundled + Versioned | No layer config | + +## Key Insights + +1. **Version Consistency**: The core sharing mechanism remains identical between Next.js 14 and 15 +2. **Layer Preparation**: Next.js 15 has layer-based sharing infrastructure ready but currently disabled +3. **Environment Priority**: The primary differentiation is server vs client, not version-based +4. **External Strategy**: Server builds treat React/Next core as external to leverage Next.js's built-in versions +5. **Future-Ready**: The commented layer-based sharing in `internal.ts` shows preparation for more granular control in Next.js 15+ \ No newline at end of file From a965d32a439a705b9bdb7e32318b6fb8f9365cc2 Mon Sep 17 00:00:00 2001 From: ScriptedAlchemy Date: Fri, 11 Jul 2025 14:20:37 -0700 Subject: [PATCH 4/4] docs: add comprehensive Next.js MF sharing information MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Added all direct import path shares (next/dist/compiled/*) - Added all vendored React builds for different contexts - Added Next.js internals shares including vendored/contexts/ - Added server-side default fallback shares - Ensured all shares from source code are documented - Improved accuracy of share configurations 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- nextjs-mf-sharing-diagram.md | 531 +++++++++++++---------------------- 1 file changed, 190 insertions(+), 341 deletions(-) diff --git a/nextjs-mf-sharing-diagram.md b/nextjs-mf-sharing-diagram.md index 21c6585f69..f4edb42f2a 100644 --- a/nextjs-mf-sharing-diagram.md +++ b/nextjs-mf-sharing-diagram.md @@ -1,298 +1,168 @@ -# Next.js Module Federation Plugin Sharing Mechanism Documentation +# Next.js Module Federation Sharing Layers and Configuration ## Overview -This document details the sharing mechanism in the Next.js Module Federation plugin, showing the sophisticated layer-based sharing system that differentiates between Next.js versions and environments. A major architectural shift occurs between Next.js 14 and 15, where version 15+ introduces granular layer-based sharing with specific share scopes. - -## Version Detection and Routing Flow - -```mermaid -flowchart TB - subgraph "Entry Point (internal.ts)" - Start[getNextInternalsShareScope] - GetVersion[getNextVersion] - CheckVersion{isNextJs15Plus?} - CheckEnv{isClient?} - end - - subgraph "Next.js 14 and Below" - Legacy14[DEFAULT_SHARE_SCOPE] - Legacy14Browser[DEFAULT_SHARE_SCOPE_BROWSER] - end - - subgraph "Next.js 15+ Client" - ClientHandler[share-internals-client.ts] - GetPagesClient[getPagesDirSharesClient] - GetAppClient[getAppDirSharesClient] - ClientResult[Layer-based Client Shares] - end - - subgraph "Next.js 15+ Server" - ServerHandler[share-internals-server.ts] - GetPagesServer[getPagesDirSharesServer] - GetAppServer[getAppDirSharesServer] - ServerResult[Layer-based Server Shares] - end - - Start --> GetVersion - GetVersion --> CheckVersion - - CheckVersion -->|Next.js < 15| CheckEnv - CheckEnv -->|Server| Legacy14 - CheckEnv -->|Client| Legacy14Browser - - CheckVersion -->|Next.js >= 15| CheckEnv - CheckEnv -->|Client| ClientHandler - CheckEnv -->|Server| ServerHandler - - ClientHandler --> GetPagesClient - ClientHandler --> GetAppClient - GetPagesClient --> ClientResult - GetAppClient --> ClientResult - - ServerHandler --> GetPagesServer - ServerHandler --> GetAppServer - GetPagesServer --> ServerResult - GetAppServer --> ServerResult -``` - -## Layer Architecture in Next.js 15+ - -```mermaid -graph TB - subgraph "Webpack Layer Names" - Shared[shared - 'shared'] - RSC[React Server Components - 'rsc'] - SSR[Server Side Rendering - 'ssr'] - ActionBrowser[Action Browser - 'action-browser'] - API[API Routes - 'api'] - Middleware[Middleware - 'middleware'] - Instrument[Instrumentation - 'instrument'] - EdgeAsset[Edge Assets - 'edge-asset'] - AppPagesBrowser[App Pages Browser - 'app-pages-browser'] - PagesDirBrowser[Pages Dir Browser - 'pages-dir-browser'] - PagesDirNode[Pages Dir Node - 'pages-dir-node'] - end - - subgraph "Share Scopes" - DefaultScope[default - Pages Directory] - AppScope[app-pages-browser - App Client] - RSCScope[reactServerComponents - RSC Layer] - SSRScope[serverSideRendering - SSR Layer] - end - - subgraph "Module Categories" - ReactModules[React Modules] - NextModules[Next.js Modules] - VendoredReact[Vendored React] - end - - PagesDirBrowser --> DefaultScope - PagesDirNode --> DefaultScope - AppPagesBrowser --> AppScope - RSC --> RSCScope - SSR --> SSRScope - - ReactModules --> VendoredReact - VendoredReact --> RSC - VendoredReact --> SSR - VendoredReact --> AppPagesBrowser - VendoredReact --> PagesDirBrowser -``` - -## Next.js 15+ Client Sharing Architecture - -```mermaid -flowchart LR - subgraph "Client Entry" - ClientCompiler[Client Compiler] - ShareClient[getNextInternalsShareScopeClient] - end - - subgraph "Pages Directory Client Shares" - subgraph "Pages React Modules" - PagesReact[react
Import: next/dist/compiled/react
Layer: pagesDirBrowser
ShareScope: default] - PagesReactDom[react-dom
Import: next/dist/compiled/react-dom
Layer: pagesDirBrowser
ShareScope: default] - PagesJSX[react/jsx-runtime
Import: next/dist/compiled/react/jsx-runtime
Layer: pagesDirBrowser
ShareScope: default] - end - subgraph "Pages Next Modules" - PagesRouter[next/router
Import: next/dist/client/router
Layer: pagesDirBrowser
ShareScope: default] - PagesHead[next/head
Layer: pagesDirBrowser
ShareScope: default] - PagesImage[next/image
Layer: pagesDirBrowser
ShareScope: default] - end - end - - subgraph "App Directory Client Shares" - subgraph "App React Modules" - AppReact[react
Import: next/dist/compiled/react
Layer: appPagesBrowser
ShareScope: app-pages-browser] - AppReactDom[react-dom
Import: next/dist/compiled/react-dom
Layer: appPagesBrowser
ShareScope: app-pages-browser] - AppServerDom[react-server-dom-webpack/client
Layer: appPagesBrowser
ShareScope: app-pages-browser] - end - subgraph "App Next Modules" - AppLink[next/link
Import: next/dist/client/app-dir/link
Layer: appPagesBrowser
ShareScope: app-pages-browser] - AppImage[next/image
Layer: appPagesBrowser
ShareScope: app-pages-browser] - AppDynamic[next/dynamic
Layer: appPagesBrowser
ShareScope: app-pages-browser] - end - end - - ClientCompiler --> ShareClient - ShareClient --> PagesReact - ShareClient --> PagesReactDom - ShareClient --> PagesJSX - ShareClient --> PagesRouter - ShareClient --> PagesHead - ShareClient --> PagesImage - ShareClient --> AppReact - ShareClient --> AppReactDom - ShareClient --> AppServerDom - ShareClient --> AppLink - ShareClient --> AppImage - ShareClient --> AppDynamic -``` - -## Next.js 15+ Server Sharing Architecture - -```mermaid -flowchart TB - subgraph "Server Entry" - ServerCompiler[Server Compiler] - ShareServer[getNextInternalsShareScopeServer] - end - - subgraph "Pages Directory Server Shares" - subgraph "Pages Server React" - SPagesReact[react
Import: next/dist/compiled/react
Layer: pagesDirNode
ShareScope: default] - SPagesReactDom[react-dom
Import: next/dist/compiled/react-dom
Layer: pagesDirNode
ShareScope: default] - end - subgraph "Pages Server Next" - SPagesRouter[next/router
Import: next/dist/client/router
Layer: pagesDirNode
ShareScope: default] - SPagesModules[next/head, next/image, next/script
Layer: pagesDirNode
ShareScope: default] - end - end - - subgraph "App Directory Server Shares" - subgraph "RSC Layer Shares" - RSCReact[react
Import: .../vendored/rsc/react
Layer: rsc
ShareScope: reactServerComponents] - RSCReactDom[react-dom
Import: .../vendored/rsc/react-dom
Layer: rsc
ShareScope: reactServerComponents] - RSCServerDom[react-server-dom-webpack/server.*
Layer: rsc
ShareScope: reactServerComponents] - end - subgraph "SSR Layer Shares" - SSRReact[react
Import: .../vendored/ssr/react
Layer: ssr
ShareScope: serverSideRendering] - SSRReactDom[react-dom
Import: .../vendored/ssr/react-dom
Layer: ssr
ShareScope: serverSideRendering] - SSRClientEdge[react-server-dom-webpack/client.edge
Layer: ssr
ShareScope: serverSideRendering] - end - end - - ServerCompiler --> ShareServer - ShareServer --> SPagesReact - ShareServer --> SPagesReactDom - ShareServer --> SPagesRouter - ShareServer --> SPagesModules - ShareServer --> RSCReact - ShareServer --> RSCReactDom - ShareServer --> RSCServerDom - ShareServer --> SSRReact - ShareServer --> SSRReactDom - ShareServer --> SSRClientEdge -``` - -## Share Configuration Structure (Next.js 15+) - -```mermaid -classDiagram - class SharedConfig { - +string request - +string shareKey - +string import - +string layer - +string|string[] issuerLayer - +string shareScope - +boolean singleton - +string version - +string requiredVersion - +string packageName - +boolean nodeModulesReconstructedLookup - } - - class PagesDirShare { - +layer: "pagesDirBrowser" | "pagesDirNode" - +shareScope: "default" - +issuerLayer: undefined | layer - } - - class AppDirClientShare { - +layer: "appPagesBrowser" - +shareScope: "app-pages-browser" - +issuerLayer: "appPagesBrowser" - } - - class AppDirServerShare { - +layer: "rsc" | "ssr" - +shareScope: "reactServerComponents" | "serverSideRendering" - +issuerLayer: layer - } - - SharedConfig <|-- PagesDirShare - SharedConfig <|-- AppDirClientShare - SharedConfig <|-- AppDirServerShare -``` - -## Detailed Sharing Comparison: Next.js 14 vs 15 - -### Client-Side Sharing +This document provides a comprehensive mapping of the Next.js Module Federation sharing mechanism, focusing on layers, share scopes, and module configurations across Next.js 14 and 15. Next.js 15+ introduces a sophisticated layer-based sharing system that isolates different rendering contexts. + +## Webpack Layers in Next.js 15+ + +| Layer Name | Constant | Purpose | Share Scope | +|------------|----------|---------|-------------| +| `shared` | WEBPACK_LAYERS.shared | Shared utilities | N/A | +| `rsc` | WEBPACK_LAYERS.reactServerComponents | React Server Components | `reactServerComponents` | +| `ssr` | WEBPACK_LAYERS.serverSideRendering | Server-side rendering | `serverSideRendering` | +| `action-browser` | WEBPACK_LAYERS.actionBrowser | Server actions browser | N/A | +| `api` | WEBPACK_LAYERS.api | API routes | N/A | +| `middleware` | WEBPACK_LAYERS.middleware | Middleware | N/A | +| `instrument` | WEBPACK_LAYERS.instrument | Instrumentation | N/A | +| `edge-asset` | WEBPACK_LAYERS.edgeAsset | Edge assets | N/A | +| `app-pages-browser` | WEBPACK_LAYERS_NAMES.appPagesBrowser | App directory client | `app-pages-browser` | +| `pages-dir-browser` | WEBPACK_LAYERS_NAMES.pagesDirBrowser | Pages directory client | `default` | +| `pages-dir-node` | WEBPACK_LAYERS_NAMES.pagesDirNode | Pages directory server | `default` | + +## Share Scopes by Environment + +| Environment | Next.js Version | Share Scope | Used By | +|-------------|----------------|-------------|---------| +| Client | 14 | `default` | All client modules | +| Server | 14 | `default` | All server modules (external) | +| Pages Dir Client | 15+ | `default` | pagesDirBrowser layer | +| Pages Dir Server | 15+ | `default` | pagesDirNode layer | +| App Dir Client | 15+ | `app-pages-browser` | appPagesBrowser layer | +| App Dir RSC | 15+ | `reactServerComponents` | rsc layer | +| App Dir SSR | 15+ | `serverSideRendering` | ssr layer | + +## Complete Client-Side Module Sharing Comparison | Module | Next.js 14 Client | Next.js 15 Pages Dir Client | Next.js 15 App Dir Client | |--------|-------------------|------------------------------|---------------------------| -| react | `import: undefined`
shareScope: default | `import: next/dist/compiled/react`
layer: pagesDirBrowser
shareScope: default | `import: next/dist/compiled/react`
layer: appPagesBrowser
shareScope: app-pages-browser | -| react-dom | `import: undefined`
shareScope: default | `import: next/dist/compiled/react-dom`
layer: pagesDirBrowser
shareScope: default | `import: next/dist/compiled/react-dom`
layer: appPagesBrowser
shareScope: app-pages-browser | -| next/router | `import: undefined`
shareScope: default | `import: next/dist/client/router`
layer: pagesDirBrowser
shareScope: default | N/A (uses next/navigation) | -| next/link | `import: undefined`
shareScope: default | Standard next/link
layer: pagesDirBrowser
shareScope: default | `import: next/dist/client/app-dir/link`
layer: appPagesBrowser
shareScope: app-pages-browser | -| react-server-dom-webpack/client | Not supported | Not used | `import: next/dist/compiled/...`
layer: appPagesBrowser
shareScope: app-pages-browser | - -### Server-Side Sharing +| **React Core** | +| react | shareScope: default
import: undefined
singleton: true | shareScope: default
import: next/dist/compiled/react
layer: pagesDirBrowser
issuerLayer: pagesDirBrowser/undefined
singleton: true | shareScope: app-pages-browser
import: next/dist/compiled/react
layer: appPagesBrowser
issuerLayer: appPagesBrowser
singleton: true | +| react/ | shareScope: default
import: undefined | shareScope: default
import: next/dist/compiled/react/
layer: pagesDirBrowser
issuerLayer: pagesDirBrowser | shareScope: app-pages-browser
import: next/dist/compiled/react/
layer: appPagesBrowser
issuerLayer: appPagesBrowser | +| next/dist/compiled/react | Not shared | shareScope: default
layer: pagesDirBrowser
issuerLayer: pagesDirBrowser
singleton: true | shareScope: app-pages-browser
layer: appPagesBrowser
issuerLayer: appPagesBrowser
singleton: true | +| react-dom | shareScope: default
import: undefined
singleton: true | shareScope: default
import: next/dist/compiled/react-dom
layer: pagesDirBrowser
issuerLayer: pagesDirBrowser/undefined
singleton: true | shareScope: app-pages-browser
import: next/dist/compiled/react-dom
layer: appPagesBrowser
issuerLayer: appPagesBrowser
singleton: true | +| react-dom/ | shareScope: default
import: undefined | shareScope: default
import: next/dist/compiled/react-dom/
layer: pagesDirBrowser
issuerLayer: pagesDirBrowser | shareScope: app-pages-browser
import: next/dist/compiled/react-dom/
layer: appPagesBrowser
issuerLayer: appPagesBrowser | +| next/dist/compiled/react-dom | Not shared | shareScope: default
layer: pagesDirBrowser
issuerLayer: pagesDirBrowser
singleton: true | shareScope: app-pages-browser
layer: appPagesBrowser
issuerLayer: appPagesBrowser
singleton: true | +| next/dist/compiled/react-dom/ | Not shared | Not shared | shareScope: app-pages-browser
layer: appPagesBrowser
issuerLayer: appPagesBrowser
singleton: true | +| react-dom/client | shareScope: default
import: undefined | shareScope: default
import: next/dist/compiled/react-dom/client
layer: pagesDirBrowser
issuerLayer: pagesDirBrowser/undefined | shareScope: app-pages-browser
import: next/dist/compiled/react-dom/client
layer: appPagesBrowser
issuerLayer: appPagesBrowser | +| next/dist/compiled/react-dom/client | Not shared | shareScope: default
layer: pagesDirBrowser
issuerLayer: pagesDirBrowser
singleton: true | shareScope: app-pages-browser
layer: appPagesBrowser
issuerLayer: appPagesBrowser
singleton: true | +| **React JSX** | +| react/jsx-runtime | shareScope: default
import: undefined
singleton: true | shareScope: default
import: next/dist/compiled/react/jsx-runtime
layer: pagesDirBrowser
issuerLayer: pagesDirBrowser/undefined
singleton: true | shareScope: app-pages-browser
import: next/dist/compiled/react/jsx-runtime
layer: appPagesBrowser
issuerLayer: appPagesBrowser
singleton: true | +| next/dist/compiled/react/jsx-runtime | Not shared | shareScope: default
layer: pagesDirBrowser
issuerLayer: pagesDirBrowser
singleton: true | shareScope: app-pages-browser
layer: appPagesBrowser
issuerLayer: appPagesBrowser
singleton: true | +| react/jsx-dev-runtime | shareScope: default
import: undefined
singleton: true | shareScope: default
import: next/dist/compiled/react/jsx-dev-runtime
layer: pagesDirBrowser
issuerLayer: pagesDirBrowser/undefined
singleton: true | shareScope: app-pages-browser
import: next/dist/compiled/react/jsx-dev-runtime
layer: appPagesBrowser
issuerLayer: appPagesBrowser
singleton: true | +| next/dist/compiled/react/jsx-dev-runtime | Not shared | shareScope: default
layer: pagesDirBrowser
issuerLayer: pagesDirBrowser
singleton: true | shareScope: app-pages-browser
layer: appPagesBrowser
issuerLayer: appPagesBrowser
singleton: true | +| **React Server Components** | +| react-server-dom-webpack/client | Not supported | Not used | shareScope: app-pages-browser
import: next/dist/compiled/react-server-dom-webpack/client
layer: appPagesBrowser
issuerLayer: appPagesBrowser
singleton: true | +| next/dist/compiled/react-server-dom-webpack/client | Not supported | Not used | shareScope: app-pages-browser
layer: appPagesBrowser
issuerLayer: appPagesBrowser
singleton: true | +| react-refresh/runtime | Not supported | Not used | shareScope: app-pages-browser
import: next/dist/compiled/react-refresh/runtime
layer: appPagesBrowser
issuerLayer: appPagesBrowser
singleton: true | +| next/dist/compiled/react-refresh/runtime | Not supported | Not used | shareScope: app-pages-browser
layer: appPagesBrowser
issuerLayer: appPagesBrowser
singleton: true | +| **Next.js Core** | +| next/router | shareScope: default
import: undefined
singleton: true | shareScope: default
import: next/dist/client/router
layer: pagesDirBrowser
issuerLayer: pagesDirBrowser/undefined
singleton: true | Not available (use next/navigation) | +| next/compat/router | shareScope: default
import: undefined | shareScope: default
import: next/dist/client/compat/router
layer: pagesDirBrowser
issuerLayer: pagesDirBrowser/undefined
singleton: true | Not available | +| next/head | shareScope: default
import: undefined
singleton: true | shareScope: default
import: next/head
layer: pagesDirBrowser
issuerLayer: pagesDirBrowser/undefined
singleton: true | Not recommended (use metadata) | +| next/image | shareScope: default
import: undefined
singleton: true | shareScope: default
import: next/image
layer: pagesDirBrowser
issuerLayer: pagesDirBrowser/undefined
singleton: true | shareScope: app-pages-browser
import: next/image
layer: appPagesBrowser
issuerLayer: appPagesBrowser
singleton: true | +| next/script | shareScope: default
import: undefined
singleton: true | shareScope: default
import: next/script
layer: pagesDirBrowser
issuerLayer: pagesDirBrowser/undefined
singleton: true | shareScope: app-pages-browser
import: next/script
layer: appPagesBrowser
issuerLayer: appPagesBrowser
singleton: true | +| next/dynamic | shareScope: default
import: undefined
singleton: true | shareScope: default
import: next/dynamic
layer: pagesDirBrowser
issuerLayer: pagesDirBrowser/undefined
singleton: true | shareScope: app-pages-browser
import: next/dynamic
layer: appPagesBrowser
issuerLayer: appPagesBrowser
singleton: true | +| next/link | shareScope: default
import: undefined
singleton: true | shareScope: default
import: next/link
layer: pagesDirBrowser
issuerLayer: undefined
singleton: true | shareScope: app-pages-browser
import: next/dist/client/app-dir/link
layer: appPagesBrowser
issuerLayer: appPagesBrowser
singleton: true
nodeModulesReconstructedLookup: true | +| next/dist/client/app-dir/link | Not shared | Not shared | shareScope: app-pages-browser
layer: appPagesBrowser
issuerLayer: appPagesBrowser
singleton: true
nodeModulesReconstructedLookup: true | +| next/dist/client/app-dir/link.js | Not shared | Not shared | shareScope: app-pages-browser
layer: appPagesBrowser
issuerLayer: appPagesBrowser
singleton: true
nodeModulesReconstructedLookup: true | +| **Next.js Internals** | +| next/dist/shared/ | Not shared | shareScope: default
import: next/dist/shared/
layer: pagesDirBrowser
issuerLayer: pagesDirBrowser
singleton: true
nodeModulesReconstructedLookup: true
include: { request: /shared-runtime/ } | shareScope: app-pages-browser
import: next/dist/shared/
layer: appPagesBrowser
issuerLayer: appPagesBrowser
singleton: true
nodeModulesReconstructedLookup: true
include: { request: /shared-runtime/ } | +| next/dist/client/ | Not shared | Not shared | shareScope: app-pages-browser
import: next/dist/client/
layer: appPagesBrowser
issuerLayer: appPagesBrowser
singleton: true
nodeModulesReconstructedLookup: true
include: { request: /request\|bfcache\|head-manager\|use-action-queue/ } | +| next/dist/compiled/ | Not shared | Not shared | shareScope: app-pages-browser
import: next/dist/compiled/
layer: appPagesBrowser
issuerLayer: appPagesBrowser
singleton: true
nodeModulesReconstructedLookup: true | + +## Complete Server-Side Module Sharing Comparison | Module | Next.js 14 Server | Next.js 15 Pages Dir Server | Next.js 15 App Dir RSC | Next.js 15 App Dir SSR | |--------|-------------------|------------------------------|------------------------|------------------------| -| react | `import: false` (external)
shareScope: default | `import: next/dist/compiled/react`
layer: pagesDirNode
shareScope: default | `import: .../vendored/rsc/react`
layer: rsc
shareScope: reactServerComponents | `import: .../vendored/ssr/react`
layer: ssr
shareScope: serverSideRendering | -| react-dom | `import: false` (external)
shareScope: default | `import: next/dist/compiled/react-dom`
layer: pagesDirNode
shareScope: default | `import: .../vendored/rsc/react-dom`
layer: rsc
shareScope: reactServerComponents | `import: .../vendored/ssr/react-dom`
layer: ssr
shareScope: serverSideRendering | -| Server DOM packages | Not supported | Not used | Various server.* imports
layer: rsc
shareScope: reactServerComponents | client.edge imports
layer: ssr
shareScope: serverSideRendering | - -## Module Resolution Flow (Next.js 15+) - -```mermaid -sequenceDiagram - participant Import as Module Import - participant Webpack as Webpack Resolver - participant Layer as Layer Matcher - participant Scope as Share Scope - participant Module as Resolved Module - - Import->>Webpack: Request module (e.g., 'react') - Webpack->>Layer: Check issuerLayer - - alt issuerLayer === 'appPagesBrowser' - Layer->>Scope: Use app-pages-browser scope - Scope->>Module: Return app-specific React - else issuerLayer === 'pagesDirBrowser' - Layer->>Scope: Use default scope - Scope->>Module: Return pages-specific React - else issuerLayer === 'rsc' - Layer->>Scope: Use reactServerComponents scope - Scope->>Module: Return RSC vendored React - else issuerLayer === 'ssr' - Layer->>Scope: Use serverSideRendering scope - Scope->>Module: Return SSR vendored React - else issuerLayer === undefined - Layer->>Scope: Check default fallbacks - Scope->>Module: Return unlayered module - end - - Module->>Import: Resolved module with correct version +| **React Core** | +| react | shareScope: default
import: false
singleton: true | shareScope: default
import: next/dist/compiled/react
layer: pagesDirNode
issuerLayer: pagesDirNode/undefined
singleton: true | shareScope: reactServerComponents
import: next/dist/server/route-modules/app-page/vendored/rsc/react
layer: rsc
issuerLayer: rsc
singleton: true | shareScope: serverSideRendering
import: next/dist/server/route-modules/app-page/vendored/ssr/react
layer: ssr
issuerLayer: ssr
singleton: true | +| next/dist/server/route-modules/app-page/vendored/rsc/react | Not supported | Not used | shareScope: reactServerComponents
layer: rsc
issuerLayer: rsc
singleton: true | Not used | +| next/dist/server/route-modules/app-page/vendored/ssr/react | Not supported | Not used | Not used | shareScope: serverSideRendering
layer: ssr
issuerLayer: ssr
singleton: true | +| react-dom | shareScope: default
import: false
singleton: true | shareScope: default
import: next/dist/compiled/react-dom
layer: pagesDirNode
issuerLayer: pagesDirNode/undefined
singleton: true | shareScope: reactServerComponents
import: next/dist/server/route-modules/app-page/vendored/rsc/react-dom
layer: rsc
issuerLayer: rsc
singleton: true | shareScope: serverSideRendering
import: next/dist/server/route-modules/app-page/vendored/ssr/react-dom
layer: ssr
issuerLayer: ssr
singleton: true | +| next/dist/server/route-modules/app-page/vendored/rsc/react-dom | Not supported | Not used | shareScope: reactServerComponents
layer: rsc
issuerLayer: rsc
singleton: true | Not used | +| next/dist/server/route-modules/app-page/vendored/ssr/react-dom | Not supported | Not used | Not used | shareScope: serverSideRendering
layer: ssr
issuerLayer: ssr
singleton: true | +| **React JSX** | +| react/jsx-runtime | shareScope: default
import: false
singleton: true | shareScope: default
import: next/dist/compiled/react/jsx-runtime
layer: pagesDirNode
issuerLayer: pagesDirNode/undefined
singleton: true | shareScope: reactServerComponents
import: next/dist/server/route-modules/app-page/vendored/rsc/react/jsx-runtime
layer: rsc
issuerLayer: rsc
singleton: true | shareScope: serverSideRendering
import: next/dist/server/route-modules/app-page/vendored/ssr/react/jsx-runtime
layer: ssr
issuerLayer: ssr
singleton: true | +| next/dist/server/route-modules/app-page/vendored/rsc/react-jsx-runtime | Not supported | Not used | shareScope: reactServerComponents
layer: rsc
issuerLayer: rsc
singleton: true | Not used | +| next/dist/server/route-modules/app-page/vendored/ssr/react-jsx-runtime | Not supported | Not used | Not used | shareScope: serverSideRendering
layer: ssr
issuerLayer: ssr
singleton: true | +| react/jsx-dev-runtime | shareScope: default
import: false
singleton: true | shareScope: default
import: next/dist/compiled/react/jsx-dev-runtime
layer: pagesDirNode
issuerLayer: pagesDirNode/undefined
singleton: true | shareScope: reactServerComponents
import: next/dist/server/route-modules/app-page/vendored/rsc/react/jsx-dev-runtime
layer: rsc
issuerLayer: rsc
singleton: true | shareScope: serverSideRendering
import: next/dist/server/route-modules/app-page/vendored/ssr/react/jsx-dev-runtime
layer: ssr
issuerLayer: ssr
singleton: true | +| next/dist/server/route-modules/app-page/vendored/rsc/react-jsx-dev-runtime | Not supported | Not used | shareScope: reactServerComponents
layer: rsc
issuerLayer: rsc
singleton: true | Not used | +| next/dist/server/route-modules/app-page/vendored/ssr/react-jsx-dev-runtime | Not supported | Not used | Not used | shareScope: serverSideRendering
layer: ssr
issuerLayer: ssr
singleton: true | +| **React Server Components** | +| react-server-dom-webpack/server.edge | Not supported | Not used | shareScope: reactServerComponents
import: next/dist/server/route-modules/app-page/vendored/rsc/react-server-dom-webpack/server.edge
layer: rsc
issuerLayer: rsc
singleton: true | Not used | +| next/dist/server/route-modules/app-page/vendored/rsc/react-server-dom-webpack-server-edge | Not supported | Not used | shareScope: reactServerComponents
layer: rsc
issuerLayer: rsc
singleton: true | Not used | +| react-server-dom-webpack/server.node | Not supported | Not used | shareScope: reactServerComponents
import: next/dist/server/route-modules/app-page/vendored/rsc/react-server-dom-webpack/server.node
layer: rsc
issuerLayer: rsc
singleton: true | Not used | +| next/dist/server/route-modules/app-page/vendored/rsc/react-server-dom-webpack-server-node | Not supported | Not used | shareScope: reactServerComponents
layer: rsc
issuerLayer: rsc
singleton: true | Not used | +| react-server-dom-webpack/client.edge | Not supported | Not used | Not used | shareScope: serverSideRendering
import: next/dist/server/route-modules/app-page/vendored/ssr/react-server-dom-webpack/client.edge
layer: ssr
issuerLayer: ssr
singleton: true | +| next/dist/server/route-modules/app-page/vendored/ssr/react-server-dom-webpack-client-edge | Not supported | Not used | Not used | shareScope: serverSideRendering
layer: ssr
issuerLayer: ssr
singleton: true | +| react-server-dom-webpack/static.edge | Not supported | Not used | shareScope: reactServerComponents
import: next/dist/server/route-modules/app-page/vendored/rsc/react-server-dom-webpack/static.edge
layer: rsc
issuerLayer: rsc
singleton: true | Not used | +| next/dist/server/route-modules/app-page/vendored/rsc/react-server-dom-webpack-static-edge | Not supported | Not used | shareScope: reactServerComponents
layer: rsc
issuerLayer: rsc
singleton: true | Not used | +| react/compiler-runtime | Not supported | Not used | shareScope: reactServerComponents
import: next/dist/server/route-modules/app-page/vendored/rsc/react/compiler-runtime
layer: rsc
issuerLayer: rsc
singleton: true | shareScope: serverSideRendering
import: next/dist/server/route-modules/app-page/vendored/ssr/react/compiler-runtime
layer: ssr
issuerLayer: ssr
singleton: true | +| next/dist/server/route-modules/app-page/vendored/rsc/react-compiler-runtime | Not supported | Not used | shareScope: reactServerComponents
layer: rsc
issuerLayer: rsc
singleton: true | Not used | +| next/dist/server/route-modules/app-page/vendored/ssr/react-compiler-runtime | Not supported | Not used | Not used | shareScope: serverSideRendering
layer: ssr
issuerLayer: ssr
singleton: true | +| **Next.js Core** | +| next/router | shareScope: default
import: false
singleton: true | shareScope: default
import: next/dist/client/router
layer: pagesDirNode
issuerLayer: pagesDirNode/undefined
singleton: true
nodeModulesReconstructedLookup: true | Not available | Not available | +| next/compat/router | Not shared | shareScope: default
import: next/dist/client/compat/router
layer: pagesDirNode
issuerLayer: pagesDirNode/undefined
singleton: true
nodeModulesReconstructedLookup: true | Not available | Not available | +| next/head | shareScope: default
import: false
singleton: true | shareScope: default
import: next/head
layer: pagesDirNode
issuerLayer: pagesDirNode/undefined
singleton: true | Not available | Not available | +| next/document | shareScope: default
import: false
singleton: true | shareScope: default
import: next/document
layer: pagesDirNode
issuerLayer: pagesDirNode/undefined
singleton: true | Not available | Not available | +| next/app | shareScope: default
import: false
singleton: true | shareScope: default
import: next/app
layer: pagesDirNode
issuerLayer: pagesDirNode/undefined
singleton: true | Not available | Not available | +| next/server | shareScope: default
import: false
singleton: true | shareScope: default
import: next/server
layer: pagesDirNode
issuerLayer: pagesDirNode/undefined
singleton: true | shareScope: reactServerComponents
import: next/server
layer: rsc
issuerLayer: rsc
singleton: true | shareScope: serverSideRendering
import: next/server
layer: ssr
issuerLayer: ssr
singleton: true | +| next/image | Not shared | shareScope: default
import: next/image
layer: pagesDirNode
issuerLayer: pagesDirNode/undefined
singleton: true | shareScope: reactServerComponents
import: next/image
layer: rsc
issuerLayer: rsc
singleton: true | shareScope: serverSideRendering
import: next/image
layer: ssr
issuerLayer: ssr
singleton: true | +| next/script | Not shared | shareScope: default
import: next/script
layer: pagesDirNode
issuerLayer: pagesDirNode/undefined
singleton: true | shareScope: reactServerComponents
import: next/script
layer: rsc
issuerLayer: rsc
singleton: true | shareScope: serverSideRendering
import: next/script
layer: ssr
issuerLayer: ssr
singleton: true | +| next/dynamic | Not shared | shareScope: default
import: next/dynamic
layer: pagesDirNode
issuerLayer: pagesDirNode/undefined
singleton: true | shareScope: reactServerComponents
import: next/dynamic
layer: rsc
issuerLayer: rsc
singleton: true | shareScope: serverSideRendering
import: next/dynamic
layer: ssr
issuerLayer: ssr
singleton: true | +| next/link | Not shared | Not shared | shareScope: reactServerComponents
import: next/dist/client/app-dir/link
layer: rsc
issuerLayer: rsc
singleton: true
nodeModulesReconstructedLookup: true | shareScope: serverSideRendering
import: next/dist/client/app-dir/link
layer: ssr
issuerLayer: ssr
singleton: true
nodeModulesReconstructedLookup: true | +| next/dist/client/app-dir/link | Not shared | Not shared | shareScope: reactServerComponents
layer: rsc
issuerLayer: rsc
singleton: true
nodeModulesReconstructedLookup: true | shareScope: serverSideRendering
layer: ssr
issuerLayer: ssr
singleton: true
nodeModulesReconstructedLookup: true | +| next/dist/client/app-dir/link.js | Not shared | Not shared | shareScope: reactServerComponents
layer: rsc
issuerLayer: rsc
singleton: true
nodeModulesReconstructedLookup: true | shareScope: serverSideRendering
layer: ssr
issuerLayer: ssr
singleton: true
nodeModulesReconstructedLookup: true | +| **Next.js Internals** | +| next/dist/compiled/next-server/* | Not shared | shareScope: default
import: next/dist/compiled/next-server/*
layer: pagesDirNode
issuerLayer: pagesDirNode
singleton: true | shareScope: reactServerComponents
import: next/dist/compiled/next-server/*
layer: rsc
issuerLayer: rsc
singleton: true | shareScope: serverSideRendering
import: next/dist/compiled/next-server/*
layer: ssr
issuerLayer: ssr
singleton: true | +| next/dist/server/route-modules/app-page/vendored/contexts/ | Not shared | Not shared | shareScope: reactServerComponents
layer: rsc
issuerLayer: rsc
singleton: true | shareScope: serverSideRendering
layer: ssr
issuerLayer: ssr
singleton: true | + +## Layer Mapping Between Next.js 14 and 15 + +| Next.js 14 Context | Next.js 14 ShareScope | Next.js 15 Layer | Next.js 15 ShareScope | Notes | +|-------------------|----------------------|------------------|----------------------|-------| +| Client (any) | default | pagesDirBrowser | default | Pages directory client-side | +| Client (any) | default | appPagesBrowser | app-pages-browser | App directory client-side | +| Server (any) | default | pagesDirNode | default | Pages directory server-side | +| Server (any) | default | rsc | reactServerComponents | React Server Components | +| Server (any) | default | ssr | serverSideRendering | Server-side rendering | +| N/A | N/A | shared | N/A | Shared utilities layer | +| N/A | N/A | api | N/A | API routes layer | +| N/A | N/A | middleware | N/A | Middleware layer | +| N/A | N/A | instrument | N/A | Instrumentation layer | +| N/A | N/A | edge-asset | N/A | Edge assets layer | +| N/A | N/A | action-browser | N/A | Server actions browser layer | + +## Module Equivalency Mapping + +| Next.js 14 Module | Next.js 15 Pages Dir | Next.js 15 App Dir | Migration Notes | +|-------------------|---------------------|-------------------|-----------------| +| react (client) | react with layer: pagesDirBrowser | react with layer: appPagesBrowser | Different share scopes | +| react (server) | react with layer: pagesDirNode | react with layer: rsc/ssr | Vendored versions in app dir | +| next/router | next/router | next/navigation | API change required | +| next/head | next/head | Metadata API | Complete API change | +| next/link | next/link | next/link (app variant) | Different import path | +| next/dynamic | next/dynamic | next/dynamic | Works in both | +| getServerSideProps | Supported | Not supported | Use server components | +| getStaticProps | Supported | Not supported | Use server components | +| _app.js | Supported | layout.js | Different file structure | +| _document.js | Supported | Not needed | Built-in to app dir | + +## Key Configuration Examples + +### Next.js 14 Client React Share +```javascript +{ + react: { + shareScope: 'default', + import: undefined, + singleton: true + } +} ``` -## Key Configuration Examples (Next.js 15+) - -### Client-Side App Directory React Configuration +### Next.js 15 App Dir Client React Share ```javascript { request: 'react', @@ -308,7 +178,7 @@ sequenceDiagram } ``` -### Server-Side RSC React Configuration +### Next.js 15 RSC React Share ```javascript { request: 'react', @@ -323,69 +193,48 @@ sequenceDiagram } ``` -## Share Scope Isolation - -```mermaid -graph TB - subgraph "Share Scope: default" - DefReact[react - Pages Dir] - DefRouter[next/router] - DefHead[next/head] - end +## IssuerLayer Logic - subgraph "Share Scope: app-pages-browser" - AppReact[react - App Dir Client] - AppLink[next/link - App variant] - AppServerDom[react-server-dom-webpack/client] - end +The `issuerLayer` field determines which modules can import a shared module: - subgraph "Share Scope: reactServerComponents" - RSCReact[react - RSC vendored] - RSCServerEdge[react-server-dom-webpack/server.edge] - RSCServerNode[react-server-dom-webpack/server.node] - end +1. **Undefined issuerLayer**: Module can be imported from any layer (fallback behavior) +2. **Specific issuerLayer**: Module can only be imported from the specified layer +3. **Array issuerLayer**: Module can be imported from any of the specified layers - subgraph "Share Scope: serverSideRendering" - SSRReact[react - SSR vendored] - SSRClientEdge[react-server-dom-webpack/client.edge] - SSRCompilerRuntime[react/compiler-runtime] - end +Example issuerLayer matching: +- `issuerLayer: 'appPagesBrowser'` - Only app directory client code can import +- `issuerLayer: undefined` - Any layer can import (unlayered) +- `issuerLayer: ['rsc', 'ssr']` - Only RSC or SSR layers can import - Note1[Isolated scopes prevent version conflicts] - Note2[Each scope maintains its own module instances] +## Additional Server-Side Default Fallback Shares (Next.js 15+) - Note1 -.-> DefReact - Note1 -.-> AppReact - Note1 -.-> RSCReact - Note1 -.-> SSRReact +These shares exist in the default shareScope without layers, providing fallback behavior for server-side code: - style Note1 fill:#ffffcc - style Note2 fill:#ffffcc -``` +| Module | shareScope | Notes | +|--------|------------|-------| +| react | default | Import: next/dist/compiled/react | +| react-dom | default | Import: next/dist/compiled/react-dom | +| react/jsx-runtime | default | Import: next/dist/compiled/react/jsx-runtime | +| react/jsx-dev-runtime | default | Import: next/dist/compiled/react/jsx-dev-runtime | +| react/compiler-runtime | default | Import: next/dist/compiled/react/compiler-runtime | +| react-server-dom-webpack/client.edge | default | Import: next/dist/compiled/react-server-dom-webpack/client.edge | +| react-server-dom-webpack/server.edge | default | Import: next/dist/compiled/react-server-dom-webpack/server.edge | +| react-server-dom-webpack/server.node | default | Import: next/dist/compiled/react-server-dom-webpack/server.node | +| react-server-dom-webpack/static.edge | default | Import: next/dist/compiled/react-server-dom-webpack/static.edge | -## Summary of Architectural Changes +## Summary of Key Differences -### Next.js 14 and Below -- Uses simple `DEFAULT_SHARE_SCOPE` and `DEFAULT_SHARE_SCOPE_BROWSER` -- Server treats React/Next as external (`import: false`) -- Client bundles everything (`import: undefined`) -- Single share scope ("default") for all modules -- No layer-based isolation +### Next.js 14 +- Single share scope: `default` +- Server modules are external (`import: false`) +- Client modules bundle everything (`import: undefined`) +- No layer isolation ### Next.js 15+ -- Sophisticated layer-based sharing with multiple share scopes -- Different vendored React versions for different layers (RSC, SSR, client) -- Complete module isolation between Pages and App directories -- Layer-specific share scopes prevent version conflicts -- Granular control over module resolution based on issuerLayer -- Support for React Server Components and advanced App Router features - -## Key Insights - -1. **Version Detection**: The system dynamically detects Next.js version and routes to appropriate sharing configuration -2. **Layer Isolation**: Next.js 15+ uses webpack layers to completely isolate different rendering contexts -3. **Vendored Dependencies**: App directory uses vendored React builds specific to each layer (RSC/SSR) -4. **Share Scope Separation**: Different share scopes prevent module conflicts between Pages and App directories -5. **Backward Compatibility**: Next.js 14 and below continue using the simpler sharing approach -6. **Granular Control**: Each module can specify exactly which layer can import it via `issuerLayer` -7. **Multiple React Instances**: The system can maintain different React versions/builds for different contexts simultaneously \ No newline at end of file +- Multiple share scopes: `default`, `app-pages-browser`, `reactServerComponents`, `serverSideRendering` +- All modules have explicit import paths +- Complete layer isolation between Pages and App directories +- Vendored React versions for different server contexts (RSC/SSR) +- IssuerLayer controls which code can import which modules +- Support for prefixed shares with `nodeModulesReconstructedLookup` +- Default fallback shares for server-side modules \ No newline at end of file