@ttsc/metro 0.16.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeongho Nam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# `@ttsc/metro`
+
+![banner of @ttsc/metro](https://ttsc.dev/og.jpg)
+
+[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/samchon/ttsc/blob/master/LICENSE) [![NPM Version](https://img.shields.io/npm/v/@ttsc/metro.svg)](https://www.npmjs.com/package/@ttsc/metro) [![NPM Downloads](https://img.shields.io/npm/dm/@ttsc/metro.svg)](https://www.npmjs.com/package/@ttsc/metro) [![Build Status](https://github.com/samchon/ttsc/workflows/test/badge.svg)](https://github.com/samchon/ttsc/actions?query=workflow%3Atest) [![Guide Documents](https://img.shields.io/badge/Guide-Documents-forestgreen)](https://ttsc.dev/docs) [![Discord Badge](https://img.shields.io/badge/discord-samchon-d91965?style=flat&labelColor=5866f2&logo=discord&logoColor=white&link=https://discord.gg/E94XhzrUCZ)](https://discord.gg/E94XhzrUCZ)
+
+Metro (React Native / Expo) adapter for `ttsc` plugins.
+
+React Native and Expo bundle with **Metro**, which transpiles each file with Babel (`babel-preset-expo` / `@react-native/metro-babel-transformer`). Babel strips TypeScript types and never runs TypeScript transformers, so neither the `ttsc` CLI nor `@ttsc/unplugin` can reach an RN/Expo build. `@ttsc/metro` wires a Metro custom transformer that runs the `ttsc` plugin pass (typia, nestia, …) on each TypeScript file, then hands the result to your existing Expo/React-Native Babel transformer.
+
+## Setup
+
+Install `ttsc` and TypeScript-Go first. Then install the Metro adapter:
+
+```bash
+npm install -D ttsc typescript@rc
+npm install -D @ttsc/metro
+```
+
+Wrap your Metro config with `withTtsc`.
+
+### Expo
+
+```js
+// metro.config.js
+const { getDefaultConfig } = require("expo/metro-config");
+const { withTtsc } = require("@ttsc/metro");
+
+module.exports = withTtsc(getDefaultConfig(__dirname));
+```
+
+### Bare React Native
+
+```js
+// metro.config.js
+const { getDefaultConfig } = require("@react-native/metro-config");
+const { withTtsc } = require("@ttsc/metro");
+
+module.exports = withTtsc(getDefaultConfig(__dirname));
+```
+
+`withTtsc` sets `transformer.babelTransformerPath` and leaves the rest of your config untouched. It auto-detects the upstream transformer to delegate to (`@expo/metro-config/babel-transformer` for Expo, then `@react-native/metro-babel-transformer`, then the legacy `metro-react-native-babel-transformer`).
+
+## Configuration
+
+By default `@ttsc/metro` finds the nearest `tsconfig.json` from the file being transformed and runs the plugins configured there: the standard `ttsc` model. If that is the config you want, `withTtsc(getDefaultConfig(__dirname))` is enough.
+
+Options are the second argument and mirror `@ttsc/unplugin`, plus a few Metro-specific knobs:
+
+```js
+module.exports = withTtsc(getDefaultConfig(__dirname), {
+  project: "tsconfig.build.json",
+  plugins: [{ transform: "typia/lib/transform" }],
+  exclude: ["__tests__"],
+});
+```
+
+- `project`: path to the `tsconfig.json` the transformer should read (resolved from `process.cwd()`).
+- `compilerOptions`: a temporary overlay layered on the selected project config.
+- `plugins`: an explicit `ttsc` plugin list override, or `false` to disable project plugins.
+- `upstreamTransformer`: an explicit module path for the Babel transformer to delegate to, when auto-detection is not what you want.
+- `include` / `exclude`: substring patterns matched against the project-relative file path, selecting which files run through the `ttsc` pass (`.ts`/`.tsx`/`.cts`/`.mts` only; declaration and JavaScript files always pass straight through).
+
+Options are forwarded from the Metro **config** process to Metro's **worker** processes through the `TTSC_METRO_OPTIONS` environment variable, so they must stay JSON-serialisable (hence substring patterns rather than `RegExp`).
+
+## How it works
+
+For each TypeScript file Metro asks to transform:
+
+1. `@ttsc/metro` runs the `ttsc` plugin pass (reusing `@ttsc/unplugin`'s transform core) → transformed **TypeScript** source.
+2. The transformed source is handed to the upstream Expo/React-Native Babel transformer, which strips types, applies the RN transforms, and returns the Babel AST Metro consumes.
+
+The plugin contract, `tsconfig` discovery, and per-build cache are identical to every other `ttsc` bundler integration.
+
+## Caveats (v1)
+
+- **Cost model.** This release reuses `@ttsc/unplugin`'s transform core, which type-checks the whole `tsconfig` project and caches the result per process. Metro runs transforms in a multi-process worker pool, so the project is compiled once per worker (on that worker's first file). A resident, incremental, per-file compiler shared across workers is the planned optimization, tracked in [samchon/ttsc#255](https://github.com/samchon/ttsc/issues/255).
+- **Cache invalidation.** Metro keys its transform cache on per-file content plus a static transformer key. A `ttsc` transform can depend on a _type_ in another file; editing that type does not change the dependent file's content, so Metro may serve a stale transform. After changing `tsconfig`/plugin configuration or a depended-upon type, restart Metro with `--reset-cache`.
+- **Type errors fail the build.** The `ttsc` pass type-checks; a project type error surfaces as a Metro build error, matching the other `ttsc` bundler integrations.
+
+## Sponsors
+
+[![Sponsors](https://raw.githubusercontent.com/samchon/sponsor-images/refs/heads/master/public/circle.svg)](https://github.com/sponsors/samchon)
+
+Thanks for your support.
+
+Your [donation](https://github.com/sponsors/samchon) encourages `ttsc` development.
+
+## References
+
+Inspired by [`@elliots/metro-transformer-typical`](https://github.com/elliots/typical/tree/main/packages/metro-transformer).

package/lib/core/options.d.ts

@@ -0,0 +1,77 @@
+import type { TtscUnpluginOptions } from "@ttsc/unplugin/api";
+/**
+ * Options accepted by {@link withTtsc} and the Metro transformer.
+ *
+ * The `project` / `compilerOptions` / `plugins` fields are inherited from
+ * `@ttsc/unplugin` so the Metro adapter speaks the exact same configuration
+ * language as every other bundler integration. The remaining fields are
+ * Metro-specific.
+ *
+ * Every field is JSON-serialisable on purpose: `withTtsc` runs in the Metro
+ * **config** process, but the transformer runs in Metro's **worker** processes,
+ * so the resolved options have to survive a structured-clone / env round-trip
+ * to reach them (see {@link serializeOptions}). That is why `include`/`exclude`
+ * are plain substring patterns rather than `RegExp`.
+ */
+export interface TtscMetroOptions extends TtscUnpluginOptions {
+    /**
+     * Explicit module path of the upstream Metro Babel transformer to delegate to
+     * after the ttsc pass.
+     *
+     * When omitted it is auto-detected: `@expo/metro-config/babel-transformer`
+     * first (Expo), then `@react-native/metro-babel-transformer`, then the legacy
+     * `metro-react-native-babel-transformer`.
+     */
+    upstreamTransformer?: string;
+    /**
+     * Substring patterns; when non-empty only files whose path contains one of
+     * them are run through the ttsc pass. Non-matching files are passed straight
+     * to the upstream transformer.
+     */
+    include?: string[];
+    /**
+     * Substring patterns; files whose path contains one of them skip the ttsc
+     * pass and go straight to the upstream transformer. Applied after
+     * {@link include}.
+     */
+    exclude?: string[];
+}
+/**
+ * Fully-resolved options, split into the ttsc-side overlay and Metro-side
+ * knobs.
+ */
+export interface ResolvedTtscMetroOptions {
+    /** Options forwarded verbatim to the `@ttsc/unplugin` transform core. */
+    ttsc: TtscUnpluginOptions;
+    /** Explicit upstream transformer module path, or `undefined` to auto-detect. */
+    upstreamTransformer?: string;
+    /** Resolved include patterns (never `undefined`). */
+    include: string[];
+    /** Resolved exclude patterns (never `undefined`). */
+    exclude: string[];
+}
+/**
+ * Environment variable that carries the resolved options from the Metro config
+ * process to the worker processes.
+ *
+ * Metro forks its transform workers (jest-worker) from the process that loaded
+ * `metro.config.js`, so a variable set on `process.env` before Metro boots is
+ * inherited by every worker. This is the only channel `withTtsc`'s arguments
+ * can reach the transformer through — the worker never sees the `withTtsc`
+ * call.
+ */
+export declare const ENV_KEY = "TTSC_METRO_OPTIONS";
+/**
+ * Serialise user options for transport to the worker processes via
+ * {@link ENV_KEY}.
+ */
+export declare function serializeOptions(options: TtscMetroOptions): string;
+/**
+ * Reconstruct the resolved options inside a worker process.
+ *
+ * Reads {@link ENV_KEY}; when it is unset or malformed the adapter falls back to
+ * defaults, which means "auto-discover `tsconfig.json` and read its configured
+ * plugins" — the standard ttsc behaviour, and the right thing for a project
+ * that called `withTtsc(config)` with no explicit options.
+ */
+export declare function resolveOptionsFromEnv(): ResolvedTtscMetroOptions;

package/lib/core/options.js

@@ -0,0 +1,76 @@
+'use strict';
+
+/**
+ * Environment variable that carries the resolved options from the Metro config
+ * process to the worker processes.
+ *
+ * Metro forks its transform workers (jest-worker) from the process that loaded
+ * `metro.config.js`, so a variable set on `process.env` before Metro boots is
+ * inherited by every worker. This is the only channel `withTtsc`'s arguments
+ * can reach the transformer through — the worker never sees the `withTtsc`
+ * call.
+ */
+const ENV_KEY = "TTSC_METRO_OPTIONS";
+/**
+ * Serialise user options for transport to the worker processes via
+ * {@link ENV_KEY}.
+ */
+function serializeOptions(options) {
+    return JSON.stringify(options ?? {});
+}
+/**
+ * Reconstruct the resolved options inside a worker process.
+ *
+ * Reads {@link ENV_KEY}; when it is unset or malformed the adapter falls back to
+ * defaults, which means "auto-discover `tsconfig.json` and read its configured
+ * plugins" — the standard ttsc behaviour, and the right thing for a project
+ * that called `withTtsc(config)` with no explicit options.
+ */
+function resolveOptionsFromEnv() {
+    const raw = process.env[ENV_KEY];
+    const parsed = parse(raw);
+    return {
+        ttsc: {
+            project: parsed.project,
+            compilerOptions: parsed.compilerOptions,
+            ...("plugins" in parsed ? { plugins: parsed.plugins } : {}),
+        },
+        upstreamTransformer: typeof parsed.upstreamTransformer === "string"
+            ? parsed.upstreamTransformer
+            : undefined,
+        include: toStringArray(parsed.include),
+        exclude: toStringArray(parsed.exclude),
+    };
+}
+function parse(raw) {
+    if (raw === undefined || raw.length === 0) {
+        return {};
+    }
+    try {
+        const value = JSON.parse(raw);
+        // Only a plain object is a valid payload; arrays, `null`, numbers, strings,
+        // and booleans (all valid JSON) degrade to defaults rather than leaking a
+        // wrong-shaped value downstream.
+        return typeof value === "object" && value !== null && !Array.isArray(value)
+            ? value
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Coerce an untrusted env value into a `string[]`. A non-array (e.g. the common
+ * mistake of passing a bare string for `include`/`exclude`) becomes `[]` so the
+ * worker never calls `.some` on a non-array and crashes.
+ */
+function toStringArray(value) {
+    return Array.isArray(value)
+        ? value.filter((entry) => typeof entry === "string")
+        : [];
+}
+
+exports.ENV_KEY = ENV_KEY;
+exports.resolveOptionsFromEnv = resolveOptionsFromEnv;
+exports.serializeOptions = serializeOptions;
+//# sourceMappingURL=options.js.map

package/lib/core/options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.js","sources":["../../src/core/options.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAyDA;;;;;;;;;AASG;AACI,MAAM,OAAO,GAAG;AAEvB;;;AAGG;AACG,SAAU,gBAAgB,CAAC,OAAyB,EAAA;IACxD,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,IAAI,EAAE,CAAC;AACtC;AAEA;;;;;;;AAOG;SACa,qBAAqB,GAAA;IACnC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC;AAChC,IAAA,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC;IACzB,OAAO;AACL,QAAA,IAAI,EAAE;YACJ,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,eAAe,EAAE,MAAM,CAAC,eAAe;AACvC,YAAA,IAAI,SAAS,IAAI,MAAM,GAAG,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC;AAC5D,SAAA;AACD,QAAA,mBAAmB,EACjB,OAAO,MAAM,CAAC,mBAAmB,KAAK;cAClC,MAAM,CAAC;AACT,cAAE,SAAS;AACf,QAAA,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,OAAO,CAAC;AACtC,QAAA,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,OAAO,CAAC;KACvC;AACH;AAEA,SAAS,KAAK,CAAC,GAAuB,EAAA;IACpC,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE;AACzC,QAAA,OAAO,EAAE;IACX;AACA,IAAA,IAAI;QACF,MAAM,KAAK,GAAY,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC;;;;AAItC,QAAA,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK;AACxE,cAAG;cACD,EAAE;IACR;AAAE,IAAA,MAAM;AACN,QAAA,OAAO,EAAE;IACX;AACF;AAEA;;;;AAIG;AACH,SAAS,aAAa,CAAC,KAAc,EAAA;AACnC,IAAA,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK;AACxB,UAAE,KAAK,CAAC,MAAM,CAAC,CAAC,KAAK,KAAsB,OAAO,KAAK,KAAK,QAAQ;UAClE,EAAE;AACR;;;;;;"}

package/lib/core/options.mjs

@@ -0,0 +1,72 @@
+/**
+ * Environment variable that carries the resolved options from the Metro config
+ * process to the worker processes.
+ *
+ * Metro forks its transform workers (jest-worker) from the process that loaded
+ * `metro.config.js`, so a variable set on `process.env` before Metro boots is
+ * inherited by every worker. This is the only channel `withTtsc`'s arguments
+ * can reach the transformer through — the worker never sees the `withTtsc`
+ * call.
+ */
+const ENV_KEY = "TTSC_METRO_OPTIONS";
+/**
+ * Serialise user options for transport to the worker processes via
+ * {@link ENV_KEY}.
+ */
+function serializeOptions(options) {
+    return JSON.stringify(options ?? {});
+}
+/**
+ * Reconstruct the resolved options inside a worker process.
+ *
+ * Reads {@link ENV_KEY}; when it is unset or malformed the adapter falls back to
+ * defaults, which means "auto-discover `tsconfig.json` and read its configured
+ * plugins" — the standard ttsc behaviour, and the right thing for a project
+ * that called `withTtsc(config)` with no explicit options.
+ */
+function resolveOptionsFromEnv() {
+    const raw = process.env[ENV_KEY];
+    const parsed = parse(raw);
+    return {
+        ttsc: {
+            project: parsed.project,
+            compilerOptions: parsed.compilerOptions,
+            ...("plugins" in parsed ? { plugins: parsed.plugins } : {}),
+        },
+        upstreamTransformer: typeof parsed.upstreamTransformer === "string"
+            ? parsed.upstreamTransformer
+            : undefined,
+        include: toStringArray(parsed.include),
+        exclude: toStringArray(parsed.exclude),
+    };
+}
+function parse(raw) {
+    if (raw === undefined || raw.length === 0) {
+        return {};
+    }
+    try {
+        const value = JSON.parse(raw);
+        // Only a plain object is a valid payload; arrays, `null`, numbers, strings,
+        // and booleans (all valid JSON) degrade to defaults rather than leaking a
+        // wrong-shaped value downstream.
+        return typeof value === "object" && value !== null && !Array.isArray(value)
+            ? value
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Coerce an untrusted env value into a `string[]`. A non-array (e.g. the common
+ * mistake of passing a bare string for `include`/`exclude`) becomes `[]` so the
+ * worker never calls `.some` on a non-array and crashes.
+ */
+function toStringArray(value) {
+    return Array.isArray(value)
+        ? value.filter((entry) => typeof entry === "string")
+        : [];
+}
+
+export { ENV_KEY, resolveOptionsFromEnv, serializeOptions };
+//# sourceMappingURL=options.mjs.map

package/lib/core/options.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.mjs","sources":["../../src/core/options.ts"],"sourcesContent":[null],"names":[],"mappings":"AAyDA;;;;;;;;;AASG;AACI,MAAM,OAAO,GAAG;AAEvB;;;AAGG;AACG,SAAU,gBAAgB,CAAC,OAAyB,EAAA;IACxD,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,IAAI,EAAE,CAAC;AACtC;AAEA;;;;;;;AAOG;SACa,qBAAqB,GAAA;IACnC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC;AAChC,IAAA,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC;IACzB,OAAO;AACL,QAAA,IAAI,EAAE;YACJ,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,eAAe,EAAE,MAAM,CAAC,eAAe;AACvC,YAAA,IAAI,SAAS,IAAI,MAAM,GAAG,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC;AAC5D,SAAA;AACD,QAAA,mBAAmB,EACjB,OAAO,MAAM,CAAC,mBAAmB,KAAK;cAClC,MAAM,CAAC;AACT,cAAE,SAAS;AACf,QAAA,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,OAAO,CAAC;AACtC,QAAA,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,OAAO,CAAC;KACvC;AACH;AAEA,SAAS,KAAK,CAAC,GAAuB,EAAA;IACpC,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE;AACzC,QAAA,OAAO,EAAE;IACX;AACA,IAAA,IAAI;QACF,MAAM,KAAK,GAAY,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC;;;;AAItC,QAAA,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK;AACxE,cAAG;cACD,EAAE;IACR;AAAE,IAAA,MAAM;AACN,QAAA,OAAO,EAAE;IACX;AACF;AAEA;;;;AAIG;AACH,SAAS,aAAa,CAAC,KAAc,EAAA;AACnC,IAAA,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK;AACxB,UAAE,KAAK,CAAC,MAAM,CAAC,CAAC,KAAK,KAAsB,OAAO,KAAK,KAAK,QAAQ;UAClE,EAAE;AACR;;;;"}

package/lib/core/upstream.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The subset of the Metro Babel-transformer contract this adapter relies on.
+ *
+ * Metro loads the module named by `transformer.babelTransformerPath` and calls
+ * its `transform` once per file, expecting a Babel AST back. `getCacheKey` is
+ * an optional export Metro folds into its transform-cache key; Metro invokes it
+ * with arguments (e.g. `{ projectRoot, enableBabelRCLookup }`), so it is typed
+ * variadic.
+ */
+export interface UpstreamTransformer {
+    transform(params: {
+        src: string;
+        filename: string;
+        options: Record<string, unknown>;
+        [key: string]: unknown;
+    }): Promise<{
+        ast: object;
+    }>;
+    getCacheKey?: (...args: unknown[]) => string;
+}
+/**
+ * Upstream transformer module specifiers tried (in order) when no explicit
+ * `upstreamTransformer` is configured: Expo first, then modern bare React
+ * Native, then the legacy package.
+ */
+export declare const UPSTREAM_CANDIDATES: readonly ["@expo/metro-config/babel-transformer", "@react-native/metro-babel-transformer", "metro-react-native-babel-transformer"];
+/**
+ * Resolve the upstream Metro Babel transformer to delegate to.
+ *
+ * Detection order, most specific first:
+ *
+ * 1. An explicit `customPath` (the `upstreamTransformer` option);
+ * 2. Each of {@link UPSTREAM_CANDIDATES} in turn.
+ *
+ * These are declared as optional peers and resolved at runtime against the
+ * consumer project, so the adapter carries no Metro/Expo dependency itself.
+ * Resolution is not memoised — Node's own module cache already makes the
+ * repeated `require` a cheap lookup, and keeping no module-level state lets a
+ * changed `upstreamTransformer` always take effect.
+ *
+ * `load` is injectable purely so the resolution order and the not-found path
+ * can be tested deterministically; production always uses the real `require`.
+ */
+export declare function resolveUpstreamTransformer(customPath?: string, load?: (modulePath: string) => UpstreamTransformer | undefined): UpstreamTransformer;

package/lib/core/upstream.js

@@ -0,0 +1,64 @@
+'use strict';
+
+var node_module = require('node:module');
+
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+const nodeRequire = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('core/upstream.js', document.baseURI).href)));
+/**
+ * Upstream transformer module specifiers tried (in order) when no explicit
+ * `upstreamTransformer` is configured: Expo first, then modern bare React
+ * Native, then the legacy package.
+ */
+const UPSTREAM_CANDIDATES = [
+    "@expo/metro-config/babel-transformer",
+    "@react-native/metro-babel-transformer",
+    "metro-react-native-babel-transformer",
+];
+/**
+ * Resolve the upstream Metro Babel transformer to delegate to.
+ *
+ * Detection order, most specific first:
+ *
+ * 1. An explicit `customPath` (the `upstreamTransformer` option);
+ * 2. Each of {@link UPSTREAM_CANDIDATES} in turn.
+ *
+ * These are declared as optional peers and resolved at runtime against the
+ * consumer project, so the adapter carries no Metro/Expo dependency itself.
+ * Resolution is not memoised — Node's own module cache already makes the
+ * repeated `require` a cheap lookup, and keeping no module-level state lets a
+ * changed `upstreamTransformer` always take effect.
+ *
+ * `load` is injectable purely so the resolution order and the not-found path
+ * can be tested deterministically; production always uses the real `require`.
+ */
+function resolveUpstreamTransformer(customPath, load = tryRequire) {
+    if (customPath !== undefined && customPath.length !== 0) {
+        const upstream = load(customPath);
+        if (upstream === undefined) {
+            throw new Error(`[@ttsc/metro] Could not load the configured upstream transformer: ${customPath}`);
+        }
+        return upstream;
+    }
+    for (const candidate of UPSTREAM_CANDIDATES) {
+        const upstream = load(candidate);
+        if (upstream !== undefined) {
+            return upstream;
+        }
+    }
+    throw new Error("[@ttsc/metro] Could not find an upstream Metro transformer. Install " +
+        "@expo/metro-config (Expo) or @react-native/metro-babel-transformer " +
+        "(React Native), or set the `upstreamTransformer` option to an explicit " +
+        "module path.");
+}
+function tryRequire(modulePath) {
+    try {
+        return nodeRequire(modulePath);
+    }
+    catch {
+        return undefined;
+    }
+}
+
+exports.UPSTREAM_CANDIDATES = UPSTREAM_CANDIDATES;
+exports.resolveUpstreamTransformer = resolveUpstreamTransformer;
+//# sourceMappingURL=upstream.js.map

package/lib/core/upstream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upstream.js","sources":["../../src/core/upstream.ts"],"sourcesContent":[null],"names":["createRequire"],"mappings":";;;;;AAEA,MAAM,WAAW,GAAGA,yBAAa,CAAC,kQAAe,CAAC;AAqBlD;;;;AAIG;AACI,MAAM,mBAAmB,GAAG;IACjC,sCAAsC;IACtC,uCAAuC;IACvC,sCAAsC;;AAGxC;;;;;;;;;;;;;;;;AAgBG;SACa,0BAA0B,CACxC,UAAmB,EACnB,OAAgE,UAAU,EAAA;IAE1E,IAAI,UAAU,KAAK,SAAS,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE;AACvD,QAAA,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC;AACjC,QAAA,IAAI,QAAQ,KAAK,SAAS,EAAE;AAC1B,YAAA,MAAM,IAAI,KAAK,CACb,qEAAqE,UAAU,CAAA,CAAE,CAClF;QACH;AACA,QAAA,OAAO,QAAQ;IACjB;AAEA,IAAA,KAAK,MAAM,SAAS,IAAI,mBAAmB,EAAE;AAC3C,QAAA,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC;AAChC,QAAA,IAAI,QAAQ,KAAK,SAAS,EAAE;AAC1B,YAAA,OAAO,QAAQ;QACjB;IACF;IAEA,MAAM,IAAI,KAAK,CACb,sEAAsE;QACpE,qEAAqE;QACrE,yEAAyE;AACzE,QAAA,cAAc,CACjB;AACH;AAEA,SAAS,UAAU,CAAC,UAAkB,EAAA;AACpC,IAAA,IAAI;AACF,QAAA,OAAO,WAAW,CAAC,UAAU,CAAwB;IACvD;AAAE,IAAA,MAAM;AACN,QAAA,OAAO,SAAS;IAClB;AACF;;;;;"}

package/lib/core/upstream.mjs

@@ -0,0 +1,60 @@
+import { createRequire } from 'node:module';
+
+const nodeRequire = createRequire(import.meta.url);
+/**
+ * Upstream transformer module specifiers tried (in order) when no explicit
+ * `upstreamTransformer` is configured: Expo first, then modern bare React
+ * Native, then the legacy package.
+ */
+const UPSTREAM_CANDIDATES = [
+    "@expo/metro-config/babel-transformer",
+    "@react-native/metro-babel-transformer",
+    "metro-react-native-babel-transformer",
+];
+/**
+ * Resolve the upstream Metro Babel transformer to delegate to.
+ *
+ * Detection order, most specific first:
+ *
+ * 1. An explicit `customPath` (the `upstreamTransformer` option);
+ * 2. Each of {@link UPSTREAM_CANDIDATES} in turn.
+ *
+ * These are declared as optional peers and resolved at runtime against the
+ * consumer project, so the adapter carries no Metro/Expo dependency itself.
+ * Resolution is not memoised — Node's own module cache already makes the
+ * repeated `require` a cheap lookup, and keeping no module-level state lets a
+ * changed `upstreamTransformer` always take effect.
+ *
+ * `load` is injectable purely so the resolution order and the not-found path
+ * can be tested deterministically; production always uses the real `require`.
+ */
+function resolveUpstreamTransformer(customPath, load = tryRequire) {
+    if (customPath !== undefined && customPath.length !== 0) {
+        const upstream = load(customPath);
+        if (upstream === undefined) {
+            throw new Error(`[@ttsc/metro] Could not load the configured upstream transformer: ${customPath}`);
+        }
+        return upstream;
+    }
+    for (const candidate of UPSTREAM_CANDIDATES) {
+        const upstream = load(candidate);
+        if (upstream !== undefined) {
+            return upstream;
+        }
+    }
+    throw new Error("[@ttsc/metro] Could not find an upstream Metro transformer. Install " +
+        "@expo/metro-config (Expo) or @react-native/metro-babel-transformer " +
+        "(React Native), or set the `upstreamTransformer` option to an explicit " +
+        "module path.");
+}
+function tryRequire(modulePath) {
+    try {
+        return nodeRequire(modulePath);
+    }
+    catch {
+        return undefined;
+    }
+}
+
+export { UPSTREAM_CANDIDATES, resolveUpstreamTransformer };
+//# sourceMappingURL=upstream.mjs.map

package/lib/core/upstream.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"upstream.mjs","sources":["../../src/core/upstream.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAEA,MAAM,WAAW,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;AAqBlD;;;;AAIG;AACI,MAAM,mBAAmB,GAAG;IACjC,sCAAsC;IACtC,uCAAuC;IACvC,sCAAsC;;AAGxC;;;;;;;;;;;;;;;;AAgBG;SACa,0BAA0B,CACxC,UAAmB,EACnB,OAAgE,UAAU,EAAA;IAE1E,IAAI,UAAU,KAAK,SAAS,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE;AACvD,QAAA,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC;AACjC,QAAA,IAAI,QAAQ,KAAK,SAAS,EAAE;AAC1B,YAAA,MAAM,IAAI,KAAK,CACb,qEAAqE,UAAU,CAAA,CAAE,CAClF;QACH;AACA,QAAA,OAAO,QAAQ;IACjB;AAEA,IAAA,KAAK,MAAM,SAAS,IAAI,mBAAmB,EAAE;AAC3C,QAAA,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC;AAChC,QAAA,IAAI,QAAQ,KAAK,SAAS,EAAE;AAC1B,YAAA,OAAO,QAAQ;QACjB;IACF;IAEA,MAAM,IAAI,KAAK,CACb,sEAAsE;QACpE,qEAAqE;QACrE,yEAAyE;AACzE,QAAA,cAAc,CACjB;AACH;AAEA,SAAS,UAAU,CAAC,UAAkB,EAAA;AACpC,IAAA,IAAI;AACF,QAAA,OAAO,WAAW,CAAC,UAAU,CAAwB;IACvD;AAAE,IAAA,MAAM;AACN,QAAA,OAAO,SAAS;IAClB;AACF;;;;"}

package/lib/index.d.ts

@@ -0,0 +1,28 @@
+import type { TtscMetroOptions } from "./core/options";
+export type { ResolvedTtscMetroOptions, TtscMetroOptions, } from "./core/options";
+/**
+ * Minimal structural type for a Metro config object — avoids a hard dependency
+ * on Metro's types while letting {@link withTtsc} preserve the caller's exact
+ * config type.
+ */
+interface MetroConfigLike {
+    transformer?: {
+        babelTransformerPath?: string;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+/**
+ * Wrap a Metro config so ttsc plugins run on every TypeScript file.
+ *
+ * Sets `transformer.babelTransformerPath` to this package's transformer and
+ * publishes the resolved options to Metro's worker processes via the
+ * {@link ENV_KEY} environment variable (the workers never see this call, so env
+ * is the transport — see `core/options.ts`). Compatible with Expo's
+ * `getDefaultConfig()` and bare React Native alike.
+ *
+ * With no `options`, the transformer auto-discovers `tsconfig.json` and runs
+ * the plugins configured there — the standard ttsc model. Pass `options` only
+ * to override the project path, plugin list, or include/exclude filters.
+ */
+export declare function withTtsc<T extends MetroConfigLike>(config: T, options?: TtscMetroOptions): T;

package/lib/index.js

@@ -0,0 +1,73 @@
+'use strict';
+
+var path = require('node:path');
+var node_url = require('node:url');
+var options = require('./core/options.js');
+
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+/**
+ * `@ttsc/metro` — Metro (React Native / Expo) adapter for ttsc plugins.
+ *
+ * Metro bundles with Babel, which strips TypeScript types and never runs ttsc
+ * plugins, so neither the `ttsc` CLI nor `@ttsc/unplugin` can reach an RN/Expo
+ * build. {@link withTtsc} wires a Metro custom transformer that runs the ttsc
+ * plugin pass on each TypeScript file before handing the result to the
+ * project's existing Expo/React-Native Babel transformer.
+ *
+ * @example
+ *   Expo```js
+ *   // metro.config.js
+ *   const { getDefaultConfig } = require("expo/metro-config");
+ *   const { withTtsc } = require("@ttsc/metro");
+ *
+ *   module.exports = withTtsc(getDefaultConfig(__dirname));
+ *   ```;
+ *
+ * @example
+ *   Bare React Native
+ *   ```js
+ *   // metro.config.js
+ *   const { getDefaultConfig } = require("@react-native/metro-config");
+ *   const { withTtsc } = require("@ttsc/metro");
+ *
+ *   module.exports = withTtsc(getDefaultConfig(__dirname));
+ *   ```
+ */
+/**
+ * Wrap a Metro config so ttsc plugins run on every TypeScript file.
+ *
+ * Sets `transformer.babelTransformerPath` to this package's transformer and
+ * publishes the resolved options to Metro's worker processes via the
+ * {@link ENV_KEY} environment variable (the workers never see this call, so env
+ * is the transport — see `core/options.ts`). Compatible with Expo's
+ * `getDefaultConfig()` and bare React Native alike.
+ *
+ * With no `options`, the transformer auto-discovers `tsconfig.json` and runs
+ * the plugins configured there — the standard ttsc model. Pass `options` only
+ * to override the project path, plugin list, or include/exclude filters.
+ */
+function withTtsc(config, options$1 = {}) {
+    process.env[options.ENV_KEY] = options.serializeOptions(options$1);
+    return {
+        ...config,
+        transformer: {
+            ...config.transformer,
+            babelTransformerPath: transformerModulePath(),
+        },
+    };
+}
+/**
+ * Absolute path to the built transformer module Metro will `require`.
+ *
+ * Always the CommonJS build (`transformer.js`) next to this module: Metro
+ * resolves `babelTransformerPath` with `require`, and `metro.config.js` is a
+ * CommonJS module. Rollup rewrites `import.meta.url` for both the CJS and ESM
+ * builds, so this resolves correctly regardless of how the config loaded this
+ * entry.
+ */
+function transformerModulePath() {
+    return path.join(path.dirname(node_url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.js', document.baseURI).href)))), "transformer.js");
+}
+
+exports.withTtsc = withTtsc;
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../src/index.ts"],"sourcesContent":[null],"names":["options","ENV_KEY","serializeOptions","join","dirname","fileURLToPath"],"mappings":";;;;;;;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BG;AAyBH;;;;;;;;;;;;AAYG;SACa,QAAQ,CACtB,MAAS,EACTA,YAA4B,EAAE,EAAA;IAE9B,OAAO,CAAC,GAAG,CAACC,eAAO,CAAC,GAAGC,wBAAgB,CAACF,SAAO,CAAC;IAChD,OAAO;AACL,QAAA,GAAG,MAAM;AACT,QAAA,WAAW,EAAE;YACX,GAAG,MAAM,CAAC,WAAW;YACrB,oBAAoB,EAAE,qBAAqB,EAAE;AAC9C,SAAA;KACG;AACR;AAEA;;;;;;;;AAQG;AACH,SAAS,qBAAqB,GAAA;AAC5B,IAAA,OAAOG,SAAI,CAACC,YAAO,CAACC,sBAAa,CAAC,0PAAe,CAAC,CAAC,EAAE,gBAAgB,CAAC;AACxE;;;;"}