fix(metro-core): normalize Windows path handling in Metro federation

.changeset/fair-eels-grab.md

@@ -0,0 +1,5 @@
+---
+'@module-federation/metro': patch
+---
+
+fix Metro Windows compatibility by normalizing path handling and source URL generation across absolute and relative entry paths, and tighten expose key resolution to avoid incorrect extension fallback matches.

packages/metro-core/__tests__/commands/utils/path-utils.spec.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest';
+import {
+  normalizeOutputRelativePath,
+  toFileSourceUrl,
+} from '../../../src/commands/utils/path-utils';
+
+describe('commands path utils', () => {
+  it('normalizes relative output paths to posix separators', () => {
+    expect(normalizeOutputRelativePath('shared\\lodash.bundle')).toBe(
+      'shared/lodash.bundle',
+    );
+  });
+
+  it('builds file urls from normalized relative paths', () => {
+    const parsed = new URL(toFileSourceUrl('exposed\\info.bundle'));
+    expect(parsed.protocol).toBe('file:');
+    expect(parsed.search).toBe('');
+    expect(parsed.hash).toBe('');
+    expect(parsed.pathname.endsWith('/exposed/info.bundle')).toBe(true);
+  });
+
+  it('encodes reserved characters as pathname segments', () => {
+    const hashParsed = new URL(toFileSourceUrl('shared/#hash.bundle'));
+    expect(hashParsed.hash).toBe('');
+    expect(hashParsed.pathname.endsWith('/shared/%23hash.bundle')).toBe(true);
+
+    const queryParsed = new URL(toFileSourceUrl('shared/?query.bundle'));
+    expect(queryParsed.search).toBe('');
+    expect(queryParsed.pathname.endsWith('/shared/%3Fquery.bundle')).toBe(true);
+
+    const percentParsed = new URL(toFileSourceUrl('shared/%25literal.bundle'));
+    expect(percentParsed.pathname.endsWith('/shared/%2525literal.bundle')).toBe(
+      true,
+    );
+  });
+});

packages/metro-core/__tests__/plugin/babel-transformer.spec.ts

@@ -0,0 +1,62 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { vol } from 'memfs';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createBabelTransformer } from '../../src/plugin/babel-transformer';
+import type { ModuleFederationConfigNormalized } from '../../src/types';
+
+function createConfig(): ModuleFederationConfigNormalized {
+  return {
+    name: 'test-app',
+    filename: 'remote.js',
+    remotes: {},
+    exposes: {},
+    shared: {},
+    shareStrategy: 'loaded-first',
+    plugins: [],
+  };
+}
+
+describe('createBabelTransformer', () => {
+  afterEach(() => {
+    vol.reset();
+    vi.restoreAllMocks();
+  });
+
+  it('escapes Windows paths for require()', () => {
+    const realReadFileSync = fs.readFileSync.bind(fs);
+    vi.spyOn(fs, 'readFileSync').mockImplementation(((filePath, options) => {
+      const targetPath = filePath.toString();
+      if (vol.existsSync(targetPath)) {
+        return vol.readFileSync(targetPath, options as never);
+      }
+      return realReadFileSync(filePath, options as never);
+    }) as typeof fs.readFileSync);
+    vi.spyOn(fs, 'writeFileSync').mockImplementation(((
+      filePath,
+      data,
+      options,
+    ) => {
+      const targetPath = filePath.toString();
+      vol.mkdirSync(path.dirname(targetPath), { recursive: true });
+      vol.writeFileSync(targetPath, data, options as never);
+    }) as typeof fs.writeFileSync);
+
+    const tmpDirPath = path.join('/virtual', '.mf');
+    vol.mkdirSync(tmpDirPath, { recursive: true });
+    const windowsPath =
+      'C:\\Users\\someone\\project\\node_modules\\metro-babel-transformer\\src\\index.js';
+
+    const outputPath = createBabelTransformer({
+      blacklistedPaths: [],
+      federationConfig: createConfig(),
+      originalBabelTransformerPath: windowsPath,
+      tmpDirPath,
+      enableInitializeCorePatching: false,
+      enableRuntimeRequirePatching: false,
+    });
+
+    const output = fs.readFileSync(outputPath, 'utf-8');
+    expect(output).toContain(`require(${JSON.stringify(windowsPath)})`);
+  });
+});

packages/metro-core/__tests__/plugin/helpers.spec.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest';
+import { toPosixPath } from '../../src/plugin/helpers';
+
+describe('toPosixPath', () => {
+  it('converts backslashes to forward slashes', () => {
+    expect(toPosixPath('C:\\Users\\someone\\project\\src\\index.js')).toBe(
+      'C:/Users/someone/project/src/index.js',
+    );
+  });
+
+  it('leaves posix paths unchanged', () => {
+    expect(toPosixPath('/usr/local/bin')).toBe('/usr/local/bin');
+  });
+});

packages/metro-core/__tests__/plugin/normalize-options.spec.ts

@@ -7,6 +7,7 @@ vi.mock('node:fs', () => {
   return { ...memfs, default: memfs };
 });
 
+import { toPosixPath } from '../../src/plugin/helpers';
 import { normalizeOptions } from '../../src/plugin/normalize-options';
 
 let projectCount = 0;
@@ -88,8 +89,8 @@ describe('normalizeOptions', () => {
       '../../src/modules/metroCorePlugin.ts',
     );
     expect(normalized.plugins).toEqual([
-      path.relative(tmpDirPath, metroCorePluginPath),
-      path.relative(tmpDirPath, runtimePluginPath),
+      toPosixPath(path.relative(tmpDirPath, metroCorePluginPath)),
+      toPosixPath(path.relative(tmpDirPath, runtimePluginPath)),
     ]);
   });
 
@@ -200,9 +201,9 @@ describe('normalizeOptions', () => {
       '../../src/modules/metroCorePlugin.ts',
     );
     expect(normalized.plugins).toEqual([
-      path.relative(tmpDirPath, metroCorePluginPath),
-      path.relative(tmpDirPath, runtimePluginPath),
-      path.relative(tmpDirPath, runtimePluginTwoPath),
+      toPosixPath(path.relative(tmpDirPath, metroCorePluginPath)),
+      toPosixPath(path.relative(tmpDirPath, runtimePluginPath)),
+      toPosixPath(path.relative(tmpDirPath, runtimePluginTwoPath)),
     ]);
   });
 

packages/metro-core/__tests__/plugin/rewrite-request.spec.ts

@@ -1,35 +1,21 @@
-import path from 'node:path';
 import { describe, expect, it } from 'vitest';
 import { createRewriteRequest } from '../../src/plugin/rewrite-request';
 
 describe('createRewriteRequest', () => {
-  it('rewrites dts asset requests to tmp dir when names are available', () => {
-    const projectRoot = '/virtual/metro-core';
+  it('normalizes manifest rewrite paths to posix separators', () => {
     const rewriteRequest = createRewriteRequest({
       config: {
-        projectRoot,
+        projectRoot: 'C:\\repo\\app',
         server: {},
       } as any,
       originalEntryFilename: 'index.js',
-      remoteEntryFilename: 'remoteEntry.js',
-      manifestPath: path.join(
-        projectRoot,
-        'node_modules',
-        '.mf-metro',
-        'mf-manifest.json',
-      ),
-      tmpDirPath: path.join(projectRoot, 'node_modules', '.mf-metro'),
-      getDtsAssetNames: () => ({
-        zipName: '@mf-types.zip',
-        apiFileName: '@mf-types.d.ts',
-      }),
+      remoteEntryFilename: 'mini.bundle',
+      manifestPath: 'C:\\repo\\app\\node_modules\\.mf\\mf-manifest.json',
+      tmpDirPath: 'C:\\repo\\app\\node_modules\\.mf',
     });
 
-    expect(rewriteRequest('/@mf-types.zip')).toBe(
-      '/node_modules/.mf-metro/@mf-types.zip',
-    );
-    expect(rewriteRequest('/@mf-types.d.ts')).toBe(
-      '/node_modules/.mf-metro/@mf-types.d.ts',
+    expect(rewriteRequest('/mf-manifest.json')).toBe(
+      '/[metro-project]/node_modules/.mf/mf-manifest.json',
     );
   });
 });

packages/metro-core/__tests__/plugin/serializer.spec.ts

@@ -0,0 +1,112 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { ConfigError } from '../../src/utils/errors';
+
+vi.mock('../../src/utils/metro-compat', () => {
+  const baseJSBundle = vi.fn(() => ({ mocked: true }));
+
+  return {
+    CountingSet: class CountingSet<T> extends Set<T> {},
+    baseJSBundle,
+    bundleToString: vi.fn(() => ({ code: 'serialized-output' })),
+  };
+});
+
+import { getModuleFederationSerializer } from '../../src/plugin/serializer';
+import { baseJSBundle } from '../../src/utils/metro-compat';
+
+function createSerializer(exposes: Record<string, string>) {
+  return getModuleFederationSerializer(
+    {
+      name: 'MFExampleMini',
+      filename: 'mini.bundle',
+      remotes: {},
+      exposes,
+      shared: {},
+      shareStrategy: 'loaded-first',
+      plugins: [],
+    },
+    true,
+  );
+}
+
+function createSerializerOptions(projectRoot = '/projectRoot') {
+  return {
+    runModule: false,
+    modulesOnly: true,
+    projectRoot,
+  } as any;
+}
+
+function createGraph() {
+  return {
+    dependencies: new Map(),
+  } as any;
+}
+
+describe('getModuleFederationSerializer', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('matches expose paths when the entry path contains backslashes', async () => {
+    const serializer = createSerializer({ './info': './src/info.tsx' });
+
+    await expect(
+      serializer(
+        '/projectRoot/src\\info.tsx',
+        [],
+        createGraph(),
+        createSerializerOptions(),
+      ),
+    ).resolves.toBe('serialized-output');
+    expect(baseJSBundle).toHaveBeenCalledTimes(1);
+  });
+
+  it('matches expose paths without extension against resolved entry files', async () => {
+    const serializer = createSerializer({ './info': './src/info' });
+
+    await expect(
+      serializer(
+        '/projectRoot/src/info.tsx',
+        [],
+        createGraph(),
+        createSerializerOptions(),
+      ),
+    ).resolves.toBe('serialized-output');
+    expect(baseJSBundle).toHaveBeenCalledTimes(1);
+  });
+
+  it('prefers exact expose path match over extensionless fallback', async () => {
+    const serializer = createSerializer({
+      './js': './src/info.js',
+      './tsx': './src/info.tsx',
+    });
+
+    await expect(
+      serializer(
+        '/projectRoot/src/info.tsx',
+        [],
+        createGraph(),
+        createSerializerOptions(),
+      ),
+    ).resolves.toBe('serialized-output');
+    expect(baseJSBundle).toHaveBeenCalledTimes(1);
+
+    const preModules = vi.mocked(baseJSBundle).mock.calls[0][1] as any[];
+    expect(preModules[0].output[0].data.code).toContain('["exposed/tsx"]');
+    expect(preModules[1].output[0].data.code).toContain('["exposed/tsx"]');
+  });
+
+  it('throws a config error when no expose entry matches', async () => {
+    const serializer = createSerializer({ './other': './src/other.tsx' });
+
+    await expect(
+      serializer(
+        '/projectRoot/src/info.tsx',
+        [],
+        createGraph(),
+        createSerializerOptions(),
+      ),
+    ).rejects.toBeInstanceOf(ConfigError);
+  });
+});

packages/metro-core/__tests__/plugin/validate-options.spec.ts

@@ -116,28 +116,54 @@ describe('validateOptions', () => {
     ).toThrow('shared');
   });
 
-  it('accepts dts as a boolean or object', () => {
+  it('throws for windows-style relative shared module names', () => {
     expect(() =>
       validateOptions({
         ...getValidConfig(),
-        dts: true,
+        shared: {
+          ...getValidConfig().shared,
+          '.\\local-shared': {
+            singleton: false,
+            eager: false,
+            version: '1.0.0',
+            requiredVersion: '1.0.0',
+          },
+        },
       } as any),
-    ).not.toThrow();
+    ).toThrow('Relative paths are not supported');
+  });
 
+  it('throws for windows-style absolute shared module names', () => {
     expect(() =>
       validateOptions({
         ...getValidConfig(),
-        dts: { generateAPITypes: true },
+        shared: {
+          ...getValidConfig().shared,
+          'C:\\project\\shared\\module': {
+            singleton: false,
+            eager: false,
+            version: '1.0.0',
+            requiredVersion: '1.0.0',
+          },
+        },
       } as any),
-    ).not.toThrow();
+    ).toThrow('Absolute paths are not supported');
   });
 
-  it('throws for invalid dts type', () => {
+  it('throws for UNC absolute shared module names', () => {
     expect(() =>
       validateOptions({
         ...getValidConfig(),
-        dts: 1,
+        shared: {
+          ...getValidConfig().shared,
+          '\\\\server\\share\\module': {
+            singleton: false,
+            eager: false,
+            version: '1.0.0',
+            requiredVersion: '1.0.0',
+          },
+        },
       } as any),
-    ).toThrow("Option 'dts' must be a boolean or a plain object.");
+    ).toThrow('Absolute paths are not supported');
   });
 });