mf-types-bundler

mf-types-bundler bundles the public declaration surface of a Module Federation remote into a compact @mf-types.zip archive.

It is designed for @module-federation/enhanced remotes that already generate DTS artifacts and need a smaller, host-compatible type archive containing only the exposed modules.

Use Cases

• Replace large compiled-types/** archives with one declaration file per exposed module.
• Validate that generated remote declarations do not leak private aliases or relative source imports.
• Run a host-like TypeScript smoke check before publishing @mf-types.zip.
• Keep the bundling logic reusable and independent from any application-specific route or component names.

Installation

npm install --save-dev mf-types-bundler

For local development with a file: dependency, build this package before loading the consuming MF config:

npm run build

Published packages are built by the prepack lifecycle before packing or publishing. Generated dist/ files are not committed.

Quick Start

const { createFederatedTypesBundler } = require('mf-types-bundler');

const name = 'remoteApp';
const exposes = {
  './Button': './src/Button.tsx',
};

module.exports = {
  name,
  exposes,
  dts: {
    generateTypes: {
      afterGenerate: createFederatedTypesBundler({
        exposes,
        name,
        shared: {
          react: { singleton: true },
          'react-dom': { singleton: true },
        },
        tsconfigPath: './tsconfig.json',
      }),
      tsConfigPath: './tsconfig.json',
    },
  },
};

See runnable-style snippets in examples/.

Agent Guide

If you are an agent integrating this package into another project, read agent-docs/using-mf-types-bundler.md before changing code.

Public API

createFederatedTypesBundler(options)

Creates an afterGenerate hook for @module-federation/enhanced DTS generation.

const { createFederatedTypesBundler } = require('mf-types-bundler');

Use this when a remote already has Module Federation exposes and dts.generateTypes configured.

bundleFederatedTypes(options)

Runs the bundling pipeline directly. This is useful for scripts and tests.

const { bundleFederatedTypes } = require('mf-types-bundler');

await bundleFederatedTypes({
  exposes: {
    './Button': './src/Button.tsx',
  },
  name: 'remoteApp',
  shared: {
    react: { singleton: true },
  },
  zipTypesPath: './dist/@mf-types.zip',
});

createFederatedTypesAssetSyncPlugin(options?)

Creates a small Webpack plugin that syncs the rewritten @mf-types.zip from disk back into the compilation assets.

Use this when Webpack emits the original zip asset before the afterGenerate hook has rewritten the file on disk.

Options

| Option | Type | Default | Description | | --- | --- | --- | --- | | name | string | required | Module Federation remote name. Used for host-like smoke imports. | | exposes | Record<string, string | { import?: string | string[] }> | required | Module Federation exposes map. | | shared | string[] | Record<string, unknown> | undefined | Shared packages that should stay external in declarations. | | externalPackages | Iterable<string> | { allow?: Iterable<string> } | undefined | Additional packages allowed in public declarations. | | allowedSideEffectImports | (string | RegExp)[] | [] | Side-effect imports that may remain in declarations. | | cwd | string | process.cwd() | Project root. | | tsconfigPath | string | ./tsconfig.json | TypeScript config used by tsdown and internal alias detection. | | packageJsonPath | string | ./package.json | Package file used to read peerDependencies. | | tempDir | string | .mf/types-bundler | Temporary build, verification, and diagnostics directory. | | verify | boolean | true | Run host-like TypeScript smoke check after rewriting the zip. | | diagnostics | boolean | true | Write diagnostics JSON to tempDir/latest.json. | | zipTypesPath | string | required for bundleFederatedTypes | Path to @mf-types.zip. Supplied by afterGenerate for hook usage. |

How It Works

1. Reads Module Federation exposes and creates one declaration entry per expose.
2. Reads package.json peerDependencies, MF shared, and explicit externalPackages to build the external package allowlist.
3. Reads tsconfig.paths and treats those path aliases as internal imports that must not leak to hosts.
4. Uses tsdown with DTS generation to bundle each exposed module into a public .d.ts file.
5. Removes asset/style side-effect imports from the bundled declarations.
6. Preserves non-asset side-effect imports so validation can reject them instead of hiding them.
7. Validates declarations for relative imports, internal aliases, file imports, forbidden side effects, and non-allowlisted packages.
8. Rewrites @mf-types.zip, removing compiled-types/** and replacing expose entries with bundled declarations.
9. Extracts the rewritten zip into a host-like @mf-types/<remoteName>/ layout and runs TypeScript against imports such as remoteName/exposeName.
10. Writes diagnostics to .mf/types-bundler/latest.json unless disabled.

Development

npm ci
npm run typecheck
npm test
npm run build
npm run pack:dry

dist/ is generated and ignored. CI builds it from source.

Requirements

• Node.js >=20.19.0
• TypeScript >=5
• A Module Federation remote using @module-federation/enhanced DTS generation

Non-Goals

• No CLI in v1.
• No app-specific expose or route logic.
• No compatibility alias for older local helper names.
• No consumer-only host type fetching.