feat(esbuild): rebuild module federation plugin architecture

.changeset/esbuild-module-federation-rebuild.md

@@ -0,0 +1,28 @@
+---
+"@module-federation/esbuild": minor
+---
+
+Completely redesigned and rebuilt the esbuild plugin from the ground up for full Module Federation support.
+
+**Breaking changes:**
+- Requires `format: 'esm'` and `splitting: true` (auto-set if not configured)
+- Requires `@module-federation/runtime` as a peer dependency
+- Remote module imports now use default export pattern (see README for migration)
+
+**New features:**
+- Shared modules via `loadShare()` with version negotiation and fallback chunks
+- Remote modules via `loadRemote()` with name@url parsing (http + https)
+- Container entry (remoteEntry.js) with standard `get()`/`init()` protocol
+- Runtime initialization with top-level await for proper async boundaries
+- Eager shared module support (static imports instead of dynamic)
+- `shareScope` configuration (global and per-module/per-remote overrides)
+- `shareStrategy` configuration (`version-first` or `loaded-first`)
+- `runtimePlugins` injection into the MF runtime
+- `publicPath` configuration for manifest and asset resolution
+- `import: false` to disable local fallback for shared modules
+- `shareKey` for custom keys in the share scope
+- `packageName` for explicit version auto-detection
+- Re-export following in export analysis (resolves `export * from`)
+- Manifest generation (mf-manifest.json) with full asset metadata
+- Subpath import handling for shared packages (e.g., `react/jsx-runtime`)
+- 117 tests covering all features

packages/esbuild/README.md

@@ -1,113 +1,278 @@
 # @module-federation/esbuild
 
-This package provides an esbuild plugin for Module Federation, enabling you to easily share code between independently built and deployed applications.
+Module Federation plugin for esbuild. Enables sharing code between independently built and deployed applications using the Module Federation protocol.
 
 ## Installation
 
-Install the package using npm:
-
 ```bash
-npm install @module-federation/esbuild
+npm install @module-federation/esbuild @module-federation/runtime
+# or
+pnpm add @module-federation/esbuild @module-federation/runtime
 ```
 
-## Usage
+## Requirements
+
+- **esbuild** `^0.25.0`
+- **format**: `'esm'` (ESM output is required for dynamic imports and top-level await)
+- **splitting**: `true` (code splitting is required for shared/exposed module chunks)
+- **@module-federation/runtime** must be installed and resolvable
+
+The plugin will automatically set `format: 'esm'` and `splitting: true` if not already configured.
+
+## Quick Start
+
+### 1. Create a Federation Config
+
+```js
+// federation.config.js
+const { withFederation } = require('@module-federation/esbuild/build');
+
+module.exports = withFederation({
+  name: 'myApp',
+  filename: 'remoteEntry.js',
+  exposes: {
+    './Button': './src/components/Button',
+  },
+  remotes: {
+    remoteApp: 'http://localhost:3001/remoteEntry.js',
+  },
+  shared: {
+    react: { singleton: true, version: '^18.2.0' },
+    'react-dom': { singleton: true, version: '^18.2.0' },
+  },
+});
+```
 
-To use the Module Federation plugin with esbuild, add it to your esbuild configuration:
+### 2. Use the Plugin in Your Build
 
 ```js
 const esbuild = require('esbuild');
-const path = require('path');
 const { moduleFederationPlugin } = require('@module-federation/esbuild/plugin');
 const federationConfig = require('./federation.config.js');
 
-async function buildApp() {
-  const tsConfig = 'tsconfig.json';
-  const outputPath = path.join('dist', 'host');
-
-  try {
-    await esbuild.build({
-      entryPoints: [path.join('host', 'main.ts')],
-      outdir: outputPath,
-      bundle: true,
-      platform: 'browser',
-      format: 'esm',
-      mainFields: ['es2020', 'browser', 'module', 'main'],
-      conditions: ['es2020', 'es2015', 'module'],
-      resolveExtensions: ['.ts', '.tsx', '.mjs', '.js'],
-      tsconfig: tsConfig,
-      splitting: true,
-      plugins: [moduleFederationPlugin(federationConfig)],
-    });
-  } catch (err) {
-    console.error(err);
-    process.exit(1);
-  }
-}
+esbuild.build({
+  entryPoints: ['./src/main.tsx'],
+  outdir: './dist',
+  bundle: true,
+  format: 'esm',
+  splitting: true,
+  plugins: [moduleFederationPlugin(federationConfig)],
+});
+```
+
+## How It Works
+
+### Architecture
+
+The plugin uses `@module-federation/runtime` directly for all Module Federation functionality. It works by intercepting module imports via esbuild's plugin hooks and replacing them with virtual modules that use the MF runtime:
+
+1. **Shared Modules**: Imports of shared dependencies (e.g., `react`) are replaced with virtual proxy modules that call `loadShare()` from the MF runtime for version negotiation between containers.
+
+2. **Remote Modules**: Imports matching remote names (e.g., `remoteApp/Button`) are replaced with virtual proxy modules that call `loadRemote()` to fetch modules from remote containers at runtime.
+
+3. **Container Entry**: When `exposes` is configured, a `remoteEntry.js` is generated with standard `get()`/`init()` exports that follow the Module Federation protocol.
+
+4. **Runtime Initialization**: Entry points are augmented with runtime initialization code that sets up the MF instance before any app code runs, using ESM top-level await.
+
+5. **Manifest**: An `mf-manifest.json` is generated for runtime discovery.
+
+### Shared Module Flow
+
+```
+┌─────────────────────────────────────────────────┐
+│ import React from 'react'                       │
+│                    │                             │
+│                    ▼                             │
+│  ┌──────────────────────────┐                   │
+│  │ Shared Proxy (virtual)    │                   │
+│  │ loadShare('react')        │                   │
+│  │   ├─ Share Scope found?   │                   │
+│  │   │  ├─ YES: use shared   │                   │
+│  │   │  └─ NO: use fallback  │───► Bundled react │
+│  │   └─ return module        │     (separate     │
+│  └──────────────────────────┘      chunk)        │
+└─────────────────────────────────────────────────┘
+```
+
+### Remote Module Flow
+
+```
+┌─────────────────────────────────────────────────┐
+│ import Button from 'remoteApp/Button'           │
+│                    │                             │
+│                    ▼                             │
+│  ┌──────────────────────────┐                   │
+│  │ Remote Proxy (virtual)    │                   │
+│  │ loadRemote('remoteApp/    │                   │
+│  │            Button')       │                   │
+│  │   ├─ Load remoteEntry.js  │                   │
+│  │   ├─ Call init(shareScope)│                   │
+│  │   ├─ Call get('./Button') │                   │
+│  │   └─ return module        │                   │
+│  └──────────────────────────┘                   │
+└─────────────────────────────────────────────────┘
+```
+
+## Configuration
+
+### `withFederation(config)`
+
+Normalizes a federation configuration object. Use this to prepare your config before passing it to `moduleFederationPlugin()`.
+
+```js
+const { withFederation } = require('@module-federation/esbuild/build');
+```
+
+#### Config Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `name` | `string` | Yes | Unique name for this federation container |
+| `filename` | `string` | No | Remote entry filename (default: `'remoteEntry.js'`) |
+| `exposes` | `Record<string, string>` | No | Modules to expose to other containers |
+| `remotes` | `Record<string, string>` | No | Remote containers to consume |
+| `shared` | `Record<string, SharedConfig>` | No | Dependencies to share between containers |
+
+#### SharedConfig
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `singleton` | `boolean` | `false` | Only allow a single version of this package |
+| `strictVersion` | `boolean` | `false` | Throw error on version mismatch |
+| `requiredVersion` | `string` | `'*'` | Required semver version range |
+| `version` | `string` | auto | The version of the shared package |
+| `eager` | `boolean` | `false` | Load shared module eagerly |
+
+### `moduleFederationPlugin(config)`
+
+Creates the esbuild plugin instance.
+
+```js
+const { moduleFederationPlugin } = require('@module-federation/esbuild/plugin');
+```
 
-buildApp();
+## Examples
 
-// Example of federation.config.js
+### Host Application (Consumer)
 
-const { withFederation, shareAll } = require('@module-federation/esbuild/build');
+```js
+// federation.config.js
+const { withFederation } = require('@module-federation/esbuild/build');
 
 module.exports = withFederation({
   name: 'host',
+  remotes: {
+    mfe1: 'http://localhost:3001/remoteEntry.js',
+  },
+  shared: {
+    react: { singleton: true, version: '^18.2.0' },
+    'react-dom': { singleton: true, version: '^18.2.0' },
+  },
+});
+```
+
+```tsx
+// App.tsx - Using remote modules
+import RemoteComponent from 'mfe1/component';
+
+export function App() {
+  return (
+    <div>
+      <h1>Host App</h1>
+      <RemoteComponent />
+    </div>
+  );
+}
+```
+
+### Remote Application (Provider)
+
+```js
+// federation.config.js
+const { withFederation } = require('@module-federation/esbuild/build');
+
+module.exports = withFederation({
+  name: 'mfe1',
   filename: 'remoteEntry.js',
   exposes: {
-    './Component': './src/Component',
+    './component': './src/MyComponent',
   },
   shared: {
-    react: {
-      singleton: true,
-      version: '^18.2.0',
-    },
-    'react-dom': {
-      singleton: true,
-      version: '^18.2.0',
-    },
-    rxjs: {
-      singleton: true,
-      version: '^7.8.1',
-    },
-    ...shareAll({
-      singleton: true,
-      strictVersion: true,
-      requiredVersion: 'auto',
-      includeSecondaries: false,
-    }),
+    react: { singleton: true, version: '^18.2.0' },
+    'react-dom': { singleton: true, version: '^18.2.0' },
   },
 });
 ```
 
-The `moduleFederationPlugin` accepts a configuration object with the following properties:
+### Both Host and Remote
 
-- `name` (string): The name of the host application.
-- `filename` (string, optional): The name of the remote entry file. Defaults to `'remoteEntry.js'`.
-- `remotes` (object, optional): An object specifying the remote applications and their entry points.
-- `exposes` (object, optional): An object specifying the modules to be exposed by the host application.
-- `shared` (array, optional): An array of package names to be shared between the host and remote applications.
+An application can be both a host and a remote simultaneously:
 
-## Plugin Features
-
-The `moduleFederationPlugin` includes the following features:
+```js
+const { withFederation } = require('@module-federation/esbuild/build');
 
-- **Virtual Share Module**: Creates a virtual module for sharing dependencies between the host and remote applications.
-- **Virtual Remote Module**: Creates a virtual module for importing exposed modules from remote applications.
-- **CommonJS to ESM Transformation**: Transforms CommonJS modules to ESM format for compatibility with Module Federation.
-- **Shared Dependencies Linking**: Links shared dependencies between the host and remote applications.
-- **Manifest Generation**: Generates a manifest file containing information about the exposed modules and their exports.
+module.exports = withFederation({
+  name: 'shell',
+  filename: 'remoteEntry.js',
+  exposes: {
+    './Header': './src/Header',
+  },
+  remotes: {
+    sidebar: 'http://localhost:3002/remoteEntry.js',
+  },
+  shared: {
+    react: { singleton: true, version: '^18.2.0' },
+    'react-dom': { singleton: true, version: '^18.2.0' },
+  },
+});
+```
 
 ## API
 
-### `moduleFederationPlugin(config)`
+### Exports from `@module-federation/esbuild/plugin`
+
+- `moduleFederationPlugin(config)` - Creates the esbuild plugin
+
+### Exports from `@module-federation/esbuild/build`
+
+- `withFederation(config)` - Normalizes federation configuration
+- `share(shareObjects)` - Processes shared dependency configurations
+- `shareAll(config)` - Shares all dependencies from package.json
+- `findPackageJson(folder)` - Finds nearest package.json
+- `lookupVersion(key, workspaceRoot)` - Looks up dependency version
+- `setInferVersion(infer)` - Enable/disable version inference
+
+### Exports from `@module-federation/esbuild`
+
+Re-exports everything from both `plugin` and `build` entry points.
+
+## Notes
+
+### Remote Module Imports Work Like Webpack
+
+All standard import forms work with remote modules, just like webpack:
+
+```tsx
+// Named imports - works!
+import { App, Button } from 'remote/component';
+
+// Default import
+import Component from 'remote/component';
+
+// Mixed default + named
+import Component, { helper } from 'remote/utils';
+
+// Aliased imports
+import { App as RemoteApp } from 'remote/component';
+
+// Namespace imports
+import * as RemoteLib from 'remote/lib';
+```
 
-Creates an esbuild plugin for Module Federation.
+The plugin automatically transforms named imports from remote modules at build time,
+converting them into a pattern that esbuild can process while preserving the natural
+import syntax you'd use with webpack.
 
-- `config` (object): The Module Federation configuration.
-  - `name` (string): The name of the host application.
-  - `filename` (string, optional): The name of the remote entry file. Defaults to `'remoteEntry.js'`.
-  - `remotes` (object, optional): An object specifying the remote applications and their entry points.
-  - `exposes` (object, optional): An object specifying the modules to be exposed by the host application.
-  - `shared` (array, optional): An array of package names to be shared between the host and remote applications.
+### Shared Module Subpaths
 
-Returns an esbuild plugin instance.
+When you share a package like `react`, subpath imports like `react/jsx-runtime` are also handled through the share scope. The plugin automatically detects subpath imports and routes them appropriately.