feat(metro-transformer): Add @rnx-kit/metro-transformer package and transformer plugins by JasonVMo · Pull Request #4022 · microsoft/rnx-kit

JasonVMo · 2026-03-10T20:09:09Z

Description

@rnx-kit/metro-transformer

The core part of this change is the addition of the @rnx-kit/metro-transformer package. This package:

Merges multiple transformer configurations together, in particular handling things like combining getTransformerOptions results which by default overwrite one another.
Ensures certain custom options are set so they can be passed to a babel transformer implementation. In particular the upstream transformer needs to be set so that if a user configures a specific transformer it can be known by another implementation.
Allows setting conditional babel transformers based on path. An example being the react-native-svg-transformer which really only needs to be run for .svg files but whenever this kind of switching had to be done people had to write their own transformer selector.
Experimental: Allows redirecting upstream resolution for babel transformers. Many of the standard transformers are aware of how to pick between the expo transformer or the react-native transformer. This allows you to effectively override the endpoint transformer to something else. (The default is typically @react-native/metro-babel-transformer.)

@rnx-kit/types-metro-config

This change also introduces the types only package @rnx-kit/types-metro-config which contains definitions for serializers, transformers, and the general shape of rnx-kit plugins.

Other changes

The transformer package is hooked into the bundle commands in the CLI by aggregating transformer configs. By default there is 1 config which comes from the metro config. If we have plugins that add additional transformer configs or if we apply the esbuild serializer transformer config the metro-transformer package will form them into a final transformer config.

the esbuild config is applied last so it will have the final word on settings.

…/jasonvmo/metro-transformer

…sformer merging and selecting babel transformers based on file type

…tion types

…/jasonvmo/metro-transformer

packages/metro-transformer/package.json

packages/metro-serializer/src/index.ts

packages/metro-transformer/package.json

packages/cli/src/helpers/metro-config.ts

packages/metro-transformer/src/babelTransformer.ts

tido64

I don't see the esbuild transformer that you've built so I'm going to assume it'll be in a separate PR. I have some questions about it:

How does it preserve the source maps?
I assume we're preprocessing source with esbuild, then pass the serialized content to upstream transformer. Are we still keeping the filename intact? Does that mean we're still using the Babel parser instead of Hermes?

packages/cli/src/helpers/metro-config.ts

packages/metro-transformer/package.json

JasonVMo · 2026-03-12T17:32:42Z

I don't see the esbuild transformer that you've built so I'm going to assume it'll be in a separate PR. I have some questions about it:

How does it preserve the source maps?

I assume we're preprocessing source with esbuild, then pass the serialized content to upstream transformer. Are we still keeping the filename intact? Does that mean we're still using the Babel parser instead of Hermes?

The esbuild transformer PR will be dependent on this one. I'll likely publish it as a draft if nothing else today though it will include these changes until they are checked in. With regards to your questions:

It sets sourcemaps to inline, with source not included, which babel knows how to parse. This results in the sourcemaps being chained together.
The esbuild transformer will take control end to end rather than routing to upstream. This will effectively replace @react-native/metro-babel-transformer. This allows removing plugins that esbuild is covering already and bypassing the ts behavior to treat those files as js files.

In my first draft of the transformer I tried renaming the files as .js and then patching the sourcemaps. This breaks the codegen plugin though as it needs the .ts filename.

tido64 · 2026-03-16T15:51:18Z

packages/cli/src/helpers/metro-config.ts

        : undefined
    );
-    Object.assign(metroConfig.transformer, esbuildTransformerConfig);
+    // otherwise, add it to the list to be merged by the MetroTransformer


Why otherwise?

tido64 · 2026-03-16T15:59:54Z

packages/cli/src/helpers/metro-config.ts

+  const transformers: ExtendedTransformerConfig[] = metroConfig.transformer
+    ? [metroConfig.transformer]
+    : [];


transformer is always set because Metro requires it. This also means that we will always run the merger logic below.

I tested this locally with only tree shaking enabled and this is what it returned:

transformOptions: { transform: { experimentalImportSupport: false, inlineRequires: false }, customTransformerOptions: { upstreamTransformerPath: '/~/node_modules/.store/@react-native-metro-babel-transformer-virtual-38655d5e06/package/src/index.js' } }

Ideally, we don't want this plugin to be running at all if it's not set.

tido64 · 2026-03-16T16:02:22Z

packages/metro-transformer/src/babelTransformer.ts

+// start with a hash of this file's contents as the cache key
+const cacheKeyParts: (string | Buffer)[] = [fs.readFileSync(__filename)];


Should this be moved inside getCacheKey? And can we avoid the fact that it's accessing disk on load, before it gets used at all?

tido64 · 2026-03-16T16:02:45Z

packages/metro-transformer/src/babelTransformer.ts

+  getCacheKey?: () => string;
+};
+
+import type { BabelTransformerArgs as BaseTransformerArgs } from "metro-babel-transformer";


Import statements should be grouped together.

tido64 · 2026-03-16T16:06:40Z

packages/metro-transformer/src/babelTransformer.ts

+/**
+ * Get the cached cache key. Will be recalculated if additional parts are added to cacheKeyParts
+ */
+export const getCacheKey = (() => {


Should we be using metro-cache-key directly? I'm also not fond of using md5 here but it looks like this comes from upstream.

tido64 · 2026-03-16T16:08:09Z

packages/metro-transformer/src/babelTransformer.ts

+  filename: string,
+  babelTransformers: Record<string, string>
+): string | undefined {
+  for (const [pattern, transformerPath] of Object.entries(babelTransformers)) {


If this happens a lot in a loop (I assume it does), it's better to iterate over an actual Map than allocating a lot of arrays and thrashing the gc.

tido64 · 2026-03-16T16:14:56Z

packages/metro-transformer/src/utilities.ts

+  let transformerPath = tryRequireResolve(baseTransformer, process.cwd());
+  if (!transformerPath) {
+    // next try to get metro-config from the package root and resolve from there
+    const metroConfigPath = tryRequireResolve(
+      `@react-native/metro-config/package.json`,
+      process.cwd()
+    );
+    if (metroConfigPath) {
+      transformerPath = tryRequireResolve(
+        baseTransformer,
+        path.dirname(metroConfigPath)
+      );
+    }
+  }


This should be inverted. The local copy should always be preferred. The one you'll find at root (if you're using node-modules linkage) is the most popular one, which is not guaranteed to be the same version being used for the current project.

tido64 · 2026-03-16T16:16:05Z

packages/metro-transformer/src/babelTransformer.ts

+  const { customTransformerOptions } = args.options
+    .customTransformOptions as unknown as {
+    customTransformerOptions: CustomTransformerOptions;
+  };


Shouldn't we be using ExtendedTransformerConfig here?

tido64 · 2026-03-16T16:17:48Z

packages/types-metro-config/tsconfig.json

+{
+  "extends": "@rnx-kit/tsconfig/tsconfig.node.json",
+  "compilerOptions": {
+    "rootDir": "src",


rootDir is not necessary if noEmit: true

Suggested change

"rootDir": "src",

JasonVMo added 12 commits March 9, 2026 13:19

first draft of the metro-transformer package

b8c5fac

add common transformer package and centralize configuration types

cd2c57e

start of cli changes

92a0bc8

Merge branch 'main' of https://github.com/microsoft/rnx-kit into user…

f788ab7

…/jasonvmo/metro-transformer

update vscode settings to use new tools

a4ebfe0

update readmes, package entries, and reduce some complexity

ebe6bc6

docs(changeset): Add @rnx-kit/metro-transformer with support for tran…

1fc3b15

…sformer merging and selecting babel transformers based on file type

docs(changeset): Consume new metro-transformer package

c87ab7e

mark types package public

e701423

docs(changeset): Add types package for common rnx-kit metro configura…

6d492db

…tion types

docs(changeset): Use new types package for serializer types

2a36067

Merge branch 'main' of https://github.com/microsoft/rnx-kit into user…

3d8be3b

…/jasonvmo/metro-transformer

JasonVMo requested review from Saadnajmi, acoates-ms and tido64 as code owners March 10, 2026 20:09

github-actions bot added feature: metro This is related to Metro feature: cli This is related to CLI labels Mar 10, 2026

remove temp file packages from the branch

0125839

github-actions bot reviewed Mar 10, 2026

View reviewed changes

packages/metro-transformer/package.json Outdated Show resolved Hide resolved

fix align deps issue

e46712f

tido64 requested changes Mar 11, 2026

View reviewed changes

microsoft-github-policy-service bot added needs author feedback and removed needs author feedback labels Mar 11, 2026

respond to PR feedback

a68124f

github-actions bot added the chore Improvements that don't directly affect features label Mar 11, 2026

JasonVMo added 2 commits March 11, 2026 11:41

another piece of PR feedback

284e3f8

fix lockfile issue

c05dbac

tido64 reviewed Mar 12, 2026

View reviewed changes

packages/cli/src/helpers/metro-config.ts Outdated Show resolved Hide resolved

packages/cli/src/helpers/metro-config.ts Outdated Show resolved Hide resolved

tido64 reviewed Mar 12, 2026

View reviewed changes

packages/metro-transformer/package.json Outdated Show resolved Hide resolved

merging and resolution fixes from pr comments

19bd442

JasonVMo requested a review from tido64 March 15, 2026 08:35

tido64 reviewed Mar 16, 2026

View reviewed changes

		// start with a hash of this file's contents as the cache key
		const cacheKeyParts: (string \| Buffer)[] = [fs.readFileSync(__filename)];

Conversation

JasonVMo commented Mar 10, 2026

Description

@rnx-kit/metro-transformer

@rnx-kit/types-metro-config

Other changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tido64 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

JasonVMo commented Mar 12, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tido64 Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

tido64 Mar 16, 2026 •

edited

Loading