@module-federation/vite

To avoid remotes bundling their own copy of @module-federation/runtime-core, you can share a single instance from a pure consumer host. This is achieved using the experiments configuration.

Implementation Pattern

1. Host (Pure Consumer): Must set experiments.provideExternalRuntime: true. This publishes the runtime to globalThis._FEDERATION_RUNTIME_CORE. Note: A host can only provide the runtime if it does not use exposes.
2. Remote: Must set experiments.externalRuntime: true. This rewrites imports of @module-federation/runtime-core to use the global instance.

Note: externalRuntime applies to the browser remote graph. SSR remotes will continue to resolve the runtime from Node.

// Host (pure consumer, no 'exposes')
federation({
  name: "host",
  remotes: {
    remote: {
      type: "module",
      name: "remote",
      entry: "http://localhost:5176/remoteEntry.js",
    },
  },
  experiments: {
    provideExternalRuntime: true,
  },
});

// Remote
federation({
  name: "remote",
  filename: "remoteEntry.js",
  exposes: {
    "./App": "./src/App.tsx",
  },
  experiments: {
    externalRuntime: true,
  },
});

A Host application consumes remotes. In your vite.config.ts, use the federation plugin to define remotes (mapping a name to an entry URL and type), shared dependencies, and other runtime behaviors like injection location and manifest generation.

import { defineConfig } from 'vite';
import { federation } from '@module-federation/vite';

export default defineConfig({
  // ...
  plugins: [
    // ...
    federation({
      name: "host",
      remotes: {
        remote: {
          type: "module", // type "var" (default) for vite remote is supported with remote's `varFilename` option
          name: "remote",
          entry: "https://[...]/remoteEntry.js",
          entryGlobalName: "remote",
          shareScope: "default",
        },
      },
      filename: "remoteEntry.js",
      shared: ["vue"],
      hostInitInjectLocation: "html", // or "entry"
      bundleAllCSS: false, // or true
      moduleParseTimeout: 10,
      moduleParseIdleTimeout: 10,
      manifest: {
        fileName: "mf-manifest.json",
        filePath: "dist/",
        disableAssetsAnalyze: false,
        additionalData: ({ stats }) => {
          stats.metaData.deployEnv = process.env.NODE_ENV;
          stats.metaData.region = "eu";
          stats.custom = {
            buildId: process.env.BUILD_ID,
          };
        },
      },
    }),
  ],
  server: {
    origin: "http://localhost:{Your port}"
  },
  // ...
});

This guide outlines the process of migrating hosts and remotes from the OriginJS plugin to @module-federation/vite.

Key Differences

• Remote Declaration: OriginJS defaults to esm for URL strings. @module-federation/vite uses a runtime model where string shorthands are treated as var remotes. Vite ESM remotes must be explicitly declared with type: 'module'.
• File Paths: By default, @module-federation/vite places the remote entry at dist/remoteEntry.js, whereas OriginJS uses dist/assets/remoteEntry.js. To maintain the old path, set filename: 'assets/remoteEntry.js' in your configuration.
• Compatibility: @module-federation/vite can consume Vite ESM remotes, var remotes (from Vite, Webpack, or Rspack), and manifests.

Requirements

Ensure your environment meets these minimum versions:

• Node.js: ^20.19.0 or >=22.12.0
• Vite: 5, 6, 7, or 8

// OriginJS host
remotes: {
  catalog: "https://cdn.example.com/catalog/remoteEntry.js",
}

// @module-federation/vite host
remotes: {
  catalog: {
    name: "catalog",
    entry: "https://cdn.example.com/catalog/remoteEntry.js",
    type: "module",
  },
}

// Consumer code (unchanged in both)
const Product = await import("catalog/Product");

Packages are published to npm using GitHub Actions trusted publishing (OIDC + provenance). The process relies on the version in package.json matching the GitHub Release tag exactly.

Standard Release Flow

1. Update Version: Update package.json to the target semver version and run pnpm install --lockfile-only if necessary.
2. Create GitHub Release: Create a release for the merge commit. The tag must match the package.json version exactly (e.g., 1.11.0) and must not start with v.
3. Automated Publish: The Publish (GitHub Release) workflow (.github/workflows/publish-on-release.yml) triggers automatically.

Distribution Tags (dist-tag)

• Stable releases: Published with the latest tag.
• Pre-releases: Published with the next tag. The workflow automatically patches the version to <base>-next.<N> (e.g., 1.12.0-next.1) before publishing.

Important Constraints

• Tag Mismatch: The publish job will hard-fail if the GitHub tag_name does not match the package.json version.
• No Dist-tag Promotion: Because the project uses Trusted Publishers (OIDC), you cannot promote a version from one dist-tag to another (e.g., using npm dist-tag add) without a full publish. If a version exists on npm but is under a different dist-tag than requested, the workflow will fail.

When migrating from @originjs/vite-plugin-federation to @module-federation/vite, do not copy the shared configuration mechanically. While many options are compatible, some require manual review or have no direct equivalent.

Configuration Mapping

React Specifics

If the host and remote use React within the same rendering boundary, you must:

1. Verify compatible versions.
2. Configure react and react-dom as singletons.
3. Verify subpath imports that cross the boundary (e.g., react/jsx-runtime and react-dom/client).

When migrating a host, you must change the remotes configuration from a simple URL string to an object specifying the type.

Crucial: A string remote in @module-federation/vite is interpreted as a var remote. For Vite ESM remotes, you must use the object syntax with type: 'module'.

To avoid introducing singleton policy issues during the initial migration, keep the shared configuration in its array form (e.g., shared: ['react']) rather than switching to object configuration immediately.

import { defineConfig } from "vite";
import { federation } from "@module-federation/vite";

export default defineConfig({
  plugins: [
    federation({
      name: "storefront",
      remotes: {
        catalog: {
          name: "catalog",
          entry: "https://cdn.example.com/catalog/remoteEntry.js",
          type: "module",
        },
      },
      shared: ["react", "react-dom"],
    }),
  ],
});