@uniflowed/react-native 0.0.0-alpha.40

package/index.js

@@ -0,0 +1,21 @@
+// @flow
+//
+// `@uniflowed/react-native`: React Native, re-exported.
+//
+// This is the real `react-native` package, not a declaration of it. uf owns the
+// Flow-first compiler, router, lints and target selection around React Native;
+// the host components, Platform object, StyleSheet runtime and native module
+// bridge stay with React Native itself.
+//
+// `export *` rather than a list of names: React Native's public JavaScript
+// surface moves with its release, and a hand-maintained copy here would turn
+// every upstream addition into a uf runtime gap.
+//
+// React Native is a peer dependency, so the application chooses the exact
+// version. uf's own release does not decide when an app moves its native host.
+
+export * from "react-native";
+
+import * as ReactNative from "react-native";
+
+export { ReactNative };

package/metro-transformer.cjs

@@ -0,0 +1,333 @@
+// @noflow
+//
+// `@uniflowed/react-native/metro-transformer.cjs`: the Babel transformer Metro
+// runs for every module in a native bundle.
+//
+// Metro loads `transformer.babelTransformerPath` with `require`, in its own
+// workers, whatever the app's config is written in — so this is CommonJS, and
+// plain JavaScript for the reason `metro.cjs` is: no process that loads it has
+// uf's hooks.
+//
+// For a module uf owns (`isFlowModule`), it runs `uf transform` — Flow's own
+// lowering, the React Compiler, the StyleX policy — and hands the result to the
+// transformer the project's Metro config already had, so Expo's preset or React
+// Native's still does everything it did before: the module system, React
+// Refresh, platform inlining. Anything else goes to that transformer untouched.
+
+"use strict";
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+/**
+ * An upstream transformer a person names on purpose. It wins over everything.
+ */
+const UPSTREAM_OVERRIDE_ENV = "UF_METRO_UPSTREAM_TRANSFORMER";
+
+/**
+ * The upstream transformer `withUniflowedMetro()` found in the config it
+ * composed.
+ *
+ * # Why the environment
+ *
+ * Metro calls a Babel transformer with `{ src, filename, options, plugins }`
+ * and nothing from the config it was loaded from — `getBabelTransformArgs` in
+ * `metro-transform-worker` builds `options` from the bundle request and five
+ * named config values — so there is no key on `transformer` this module could
+ * read the upstream from. The environment is the one channel that reaches it:
+ * the config is evaluated before Metro starts its workers, and a worker, child
+ * process or thread, starts with a copy of the environment it was created from.
+ *
+ * A name of its own, rather than reusing `UF_METRO_UPSTREAM_TRANSFORMER`,
+ * because the two say different things. That one is a person overriding the
+ * upstream, and it wins; this one is what the project's config already said,
+ * and it is written again every time a config is composed.
+ */
+const CONFIGURED_UPSTREAM_ENV = "UF_METRO_CONFIGURED_UPSTREAM";
+
+let host = null;
+let upstream = null;
+
+async function transform(args) {
+  const { src, filename, options } = args;
+  const projectRoot = projectRootOf(options);
+  const flow = loadHost();
+  const absolute = path.isAbsolute(filename) ? filename : path.join(projectRoot, filename);
+  let next = src;
+
+  if (flow.isFlowModule(absolute)) {
+    findUfBinary(flow);
+    const out = await flow.transformFlow(src, absolute, {
+      root: projectRoot,
+      development: options?.dev === true,
+      // Off, because the upstream transformer registers components for React
+      // Refresh itself — Expo's preset and React Native's both add
+      // `react-refresh/babel` to a development bundle — and a component
+      // registered twice is two families to the runtime, and a refresh that
+      // remounts instead of preserving state.
+      refresh: false,
+      sourceMap: true,
+    });
+    if (out != null) {
+      if (out.css != null && out.css !== "") {
+        throw new Error(
+          `@uniflowed/react-native/metro: ${filename} produced StyleX CSS, but the ` +
+            "native Metro contract cannot attach CSS to a React Native bundle yet. " +
+            "Use native style props or keep that StyleX module out of the native route.",
+        );
+      }
+      next = out.code;
+    }
+  }
+
+  // Everything Metro passed, and not a chosen subset of it. `plugins` carries
+  // Metro's `functionMapBabelPlugin` and `importLocationsPlugin`, and
+  // forwarding `{ src, filename, options }` alone dropped both for every Flow
+  // module in the bundle — function names in stack traces among them.
+  return loadUpstream(projectRoot).transformer.transform({
+    ...args,
+    src: next,
+    // RN's Babel transformer still gates React Refresh on `hot`, although
+    // recent Metro versions omit it. Preserve an explicit caller decision.
+    options: { ...options, hot: options?.hot ?? options?.dev === true },
+  });
+}
+
+/**
+ * The cache key Metro files every transformed module under.
+ *
+ * Four identities, because four things decide what a module compiles to: this
+ * file, the JavaScript side of `uf transform`, the `uf` binary that does the
+ * compiling, and the upstream transformer with its own key. The binary is the
+ * one that was missing. A rebuilt or upgraded `uf` changes the output of every
+ * Flow module without touching any file this key used to hash, so Metro went on
+ * serving the old transforms until somebody thought to pass `--reset-cache` —
+ * the defect `@uniflowed/host`'s own cache keys on `ufBinaryIdentity()` to
+ * avoid.
+ */
+function getCacheKey(options) {
+  const projectRoot = projectRootOf(options);
+  const flow = loadHost();
+  const binary = findUfBinary(flow);
+  const loaded = loadUpstream(projectRoot);
+  const parts = [
+    "uniflowed-react-native-metro-transformer-v2",
+    fileIdentity(__filename),
+    fileIdentity(require.resolve("@uniflowed/host/transform")),
+    flow.ufBinaryIdentity(binary) ?? binary,
+    loaded.path,
+  ];
+  if (typeof loaded.transformer.getCacheKey === "function") {
+    parts.push(String(loaded.transformer.getCacheKey(options)));
+  }
+  return parts.join("\0");
+}
+
+/**
+ * `@uniflowed/host/transform`, loaded synchronously.
+ *
+ * It is an ES module and this file is not, and `getCacheKey` has to answer
+ * synchronously: Metro asks it once, on its main thread, before the first
+ * transform. `require` of an ES module is what Node 20.19 and 22.12 added, and
+ * on an older Node the error says that rather than failing on a name.
+ */
+function loadHost() {
+  if (host != null) return host;
+  try {
+    host = require("@uniflowed/host/transform");
+  } catch (error) {
+    if (error?.code === "ERR_REQUIRE_ESM") {
+      throw new Error(
+        `@uniflowed/react-native/metro: Node ${process.version} cannot require @uniflowed/host, ` +
+          "which is an ES module. Run Metro on Node 20.19, 22.12 or later.",
+      );
+    }
+    throw error;
+  }
+  return host;
+}
+
+/**
+ * The `uf` that compiles this bundle, found the way its installer arranged and
+ * handed to `@uniflowed/host` through `UF_BINARY`.
+ *
+ * In order: `UF_BINARY`, which `uf dev` sets to itself so a bundle compiles
+ * with exactly the `uf` that started it; `uf` on `PATH`; and the installer's
+ * own directory, `UF_BIN_DIR` or `~/.local/bin`. The last is there for the
+ * processes that bundle an app without a person's shell in front of them —
+ * Xcode's "Bundle React Native code and images" phase runs with a minimal
+ * `PATH`, and a `uf` the installer put in `~/.local/bin` is invisible to it.
+ *
+ * Found once and written back to `UF_BINARY`, so that the binary this key
+ * identifies and the binary `@uniflowed/host` spawns cannot be two different
+ * files.
+ */
+function findUfBinary(flow) {
+  const named = process.env.UF_BINARY;
+  if (named != null && named !== "") return named;
+  if (flow.ufBinaryIdentity("uf") != null) return "uf";
+  const directory = process.env.UF_BIN_DIR || path.join(os.homedir(), ".local", "bin");
+  const installed = path.join(directory, "uf");
+  if (flow.ufBinaryIdentity(installed) != null) {
+    process.env.UF_BINARY = installed;
+    return installed;
+  }
+  throw new Error(
+    "@uniflowed/react-native/metro: cannot find the `uf` binary that compiles Flow for this bundle. " +
+      `UF_BINARY is not set, \`uf\` is not on PATH (${process.env.PATH ?? ""}), ` +
+      `and there is no executable at ${installed}. ` +
+      "Install uf with `curl -fsSL https://setup.uniflowed.dev | sh`, or set UF_BINARY to its path — " +
+      "for Xcode's bundle phase, export it from ios/.xcode.env.local.",
+  );
+}
+
+/**
+ * The Babel transformer that runs after uf's, loaded once per worker.
+ *
+ * An upstream named by a person or by the composed config is the only
+ * candidate: if it does not load, that is an error, not an invitation to
+ * guess. Only a config that never went through `withUniflowedMetro()` falls
+ * back to looking for the transformer the project's own Metro config would
+ * have named.
+ */
+function loadUpstream(projectRoot) {
+  if (upstream != null) return upstream;
+  const override = process.env[UPSTREAM_OVERRIDE_ENV];
+  const configured = process.env[CONFIGURED_UPSTREAM_ENV];
+  let candidates;
+  if (override != null && override !== "") {
+    candidates = [{ request: override, from: projectRoot, why: UPSTREAM_OVERRIDE_ENV }];
+  } else if (configured != null && configured !== "") {
+    candidates = [
+      {
+        request: configured,
+        from: projectRoot,
+        why: "transformer.babelTransformerPath, composed by withUniflowedMetro()",
+      },
+    ];
+  } else {
+    candidates = installedCandidates(projectRoot);
+  }
+
+  const tried = [];
+  for (const candidate of candidates) {
+    let resolved;
+    try {
+      resolved = require.resolve(candidate.request, { paths: [candidate.from] });
+    } catch {
+      tried.push(`${candidate.request} (${candidate.why}): not found from ${candidate.from}`);
+      continue;
+    }
+    const loaded = require(resolved);
+    const transformer =
+      loaded?.__esModule === true && loaded.default != null ? loaded.default : loaded;
+    if (typeof transformer?.transform !== "function") {
+      tried.push(`${resolved} (${candidate.why}): does not export transform()`);
+      continue;
+    }
+    if (transformer.isUniflowedMetroTransformer === true) {
+      throw new Error(
+        `@uniflowed/react-native/metro: ${resolved} is uf's own Metro transformer, named as the ` +
+          "transformer to run after uf's. Two copies of @uniflowed/react-native have composed the " +
+          "same config; install one.",
+      );
+    }
+    upstream = { transformer, path: resolved };
+    return upstream;
+  }
+
+  throw new Error(
+    "@uniflowed/react-native/metro: there is no React Native Babel transformer to run after uf's. " +
+      "Compose the project's Metro config so the transformer it already has keeps running — " +
+      "`module.exports = withUniflowedMetro(getDefaultConfig(__dirname))`, with getDefaultConfig " +
+      "from expo/metro-config or @react-native/metro-config — or set UF_METRO_UPSTREAM_TRANSFORMER " +
+      "to a transformer's path.\n" +
+      tried.map((line) => `  ${line}`).join("\n"),
+  );
+}
+
+/**
+ * The transformers a project's own Metro config would have named, most likely
+ * first.
+ *
+ * Looked up from the project, not from this package. A package manager is free
+ * to nest `@expo/metro-config` inside `expo` — npm does, for the SDK 57
+ * template — and a `require` from here sees only what was hoisted, which is why
+ * this list could not find Expo's transformer in a freshly created Expo app.
+ *
+ * Expo's first when the project has Expo, because in an Expo project it is the
+ * one `getDefaultConfig()` names and React Native's would bundle without
+ * `babel-preset-expo`. `metro-babel-transformer`, which this list used to end
+ * with, is gone from it: it applies no React Native preset, so reaching it meant
+ * React Native's own Flow source arriving at Babel with nothing to strip it — a
+ * failure much further from its cause than this refusal.
+ */
+function installedCandidates(projectRoot) {
+  const candidates = [];
+  const expo = packageDirectory("expo", projectRoot);
+  if (expo != null) {
+    candidates.push({
+      request: "@expo/metro-config/babel-transformer",
+      from: expo,
+      why: "Expo's transformer, beside the installed expo",
+    });
+  }
+  candidates.push({
+    request: "@react-native/metro-babel-transformer",
+    from: projectRoot,
+    why: "React Native's transformer",
+  });
+  const reactNative = packageDirectory("react-native", projectRoot);
+  if (reactNative != null) {
+    candidates.push({
+      request: "@react-native/metro-babel-transformer",
+      from: reactNative,
+      why: "React Native's transformer, beside the installed react-native",
+    });
+  }
+  candidates.push({
+    request: "metro-react-native-babel-transformer",
+    from: projectRoot,
+    why: "React Native's transformer before 0.73",
+  });
+  return candidates;
+}
+
+/**
+ * The directory `name` is installed in, looked up the way Node looks up a
+ * package — `node_modules` in the starting directory and then in each parent.
+ *
+ * Walked rather than resolved, because `require.resolve("expo/package.json")`
+ * depends on the package's `exports` allowing it, and the question here is only
+ * whether the package is installed.
+ */
+function packageDirectory(name, from) {
+  let directory = from;
+  for (;;) {
+    const candidate = path.join(directory, "node_modules", name);
+    if (fs.existsSync(path.join(candidate, "package.json"))) return candidate;
+    const parent = path.dirname(directory);
+    if (parent === directory) return null;
+    directory = parent;
+  }
+}
+
+function projectRootOf(options) {
+  return typeof options?.projectRoot === "string" ? options.projectRoot : process.cwd();
+}
+
+function fileIdentity(file) {
+  const stat = fs.statSync(file);
+  return `${file}:${stat.size}:${stat.mtimeMs}`;
+}
+
+module.exports = {
+  transform,
+  getCacheKey,
+  // Read by `loadUpstream`, so a config composed by two copies of this package
+  // is refused instead of recursing into itself.
+  isUniflowedMetroTransformer: true,
+  // The name `metro.cjs` writes the composed upstream under, kept in one place.
+  configuredUpstreamEnv: CONFIGURED_UPSTREAM_ENV,
+};

package/metro.cjs

@@ -0,0 +1,205 @@
+// @noflow
+//
+// `@uniflowed/react-native/metro`: the Metro half of uf's native target.
+//
+// # Why this module is CommonJS rather than Flow
+//
+// Every other module in `@uniflowed/*` is Flow, because `uf` is the process
+// that loads it and `uf` installs the hooks that make Flow run. This one is
+// loaded by somebody else's process. Metro evaluates `metro.config.js` in
+// plain Node — under `expo start`, `react-native start`, the bundle phases
+// Xcode and Gradle run, and on EAS Build's machines — and none of those has
+// heard of uf's loader. Until ubugeeei-prod/uf#988 this file was Flow, and
+// outside `uf test` importing it was `SyntaxError: Unexpected token 'export'`.
+// The suite never saw that, because the suite is the one place the hooks are
+// always installed.
+//
+// CommonJS rather than an ES module, because every template that writes a
+// Metro config writes CommonJS — `require("expo/metro-config")`,
+// `require("@react-native/metro-config")` — and an ES module config can still
+// `import { withUniflowedMetro } from "@uniflowed/react-native/metro"`: Node
+// reads a CommonJS module's named exports. The other direction, `require` of
+// an ES module, needs Node 20.19 or 22.12.
+//
+// `uf build --target native` writes the same extension list and pipeline into
+// the build manifest's target contract, so what a finished build reports and
+// what a project's Metro config does are one answer rather than two.
+
+"use strict";
+
+const path = require("node:path");
+
+const { configuredUpstreamEnv } = require("./metro-transformer.cjs");
+
+/** Source extensions uf's native target needs, added to the project's own. */
+const metroSourceExts = Object.freeze(["js", "jsx", "mjs", "cjs"]);
+
+/** The `package.json` fields Metro reads for an entry point, in order. */
+const metroResolverMainFields = Object.freeze(["react-native", "browser", "main"]);
+
+/** What a module goes through, in order, on its way into a native bundle. */
+const metroTransformPipeline = Object.freeze([
+  "flow",
+  "react-compiler",
+  "stylex-css-refusal",
+  "metro-babel",
+]);
+
+/** The Babel transformer Metro runs, as the absolute path Metro wants. */
+const metroTransformerPath = path.join(__dirname, "metro-transformer.cjs");
+
+const nativePackages = Object.freeze([
+  "brand",
+  "cell",
+  "core",
+  "effect",
+  "fetch",
+  "form",
+  "graphql",
+  "hooks",
+  "i18n",
+  "immer",
+  "query",
+  "react",
+  "react-native",
+  "relay",
+  "state",
+  "temporal",
+  "validator",
+]);
+const domPackages = new Set([
+  "ui",
+  "web",
+  "browser",
+  "react-testing",
+  "story",
+  "vrt",
+  "pwa",
+  "motion",
+]);
+
+function nativeResolution(previous) {
+  return (context, moduleName, platform) => {
+    const name = moduleName.startsWith("@uniflowed/") ? moduleName.split("/")[1] : null;
+    if (
+      domPackages.has(name) ||
+      (name === "router" &&
+        moduleName !== "@uniflowed/router/native" &&
+        moduleName !== "@uniflowed/router/routing")
+    ) {
+      throw new Error(
+        `${moduleName} needs a browser DOM and cannot be bundled for ${platform}. ` +
+          `Native packages: ${nativePackages.map((item) => `@uniflowed/${item}`).join(", ")}, ` +
+          "@uniflowed/router/native and @uniflowed/router/routing. Keep DOM components in $page.web.js.",
+      );
+    }
+    return (previous ?? context.resolveRequest)(context, moduleName, platform);
+  };
+}
+
+/**
+ * Add uf's source extensions, resolver fields and transformer to a Metro config.
+ *
+ * Metro already owns platform suffix resolution (`.ios.js`, `.android.js`,
+ * `.native.js`), and uf's route scanner uses the same suffixes, so nothing
+ * about that is declared again here.
+ *
+ * # Composing with the transformer that is already there
+ *
+ * Metro accepts one `babelTransformerPath`, and every real config already has
+ * one: `getDefaultConfig()` names Expo's in `expo/metro-config` and React
+ * Native's in `@react-native/metro-config`. This function used to refuse such a
+ * config, which left a hand-written object as the only input it accepted —
+ * `withUniflowedMetro(getDefaultConfig(__dirname))` threw in every project that
+ * had ever been generated.
+ *
+ * Replacing that transformer would be worse than refusing it. Expo's is how
+ * `babel-preset-expo`, Expo Router and React Refresh reach a module, and a
+ * custom one — an SVG transformer, say — is a decision the project made. So the
+ * transformer that was there keeps running, after uf's and on uf's output, and
+ * uf's takes its place in the config.
+ *
+ * Metro gives a Babel transformer nothing from the config it came from, so the
+ * one being composed travels to Metro's workers in the environment; see
+ * `configuredUpstreamEnv` in `metro-transformer.cjs` for why that is the only
+ * channel there is. A transformer the config names by package is resolved here,
+ * from the project root, where Metro would have resolved it — so a transformer
+ * that is not installed is an error while the config loads, not in a worker
+ * halfway through the first bundle.
+ *
+ * Composing twice is composing once: a config whose transformer is already
+ * uf's is returned with nothing recorded, so wrapping a config a library has
+ * already wrapped cannot make uf's transformer its own upstream.
+ *
+ * @param {object} [config] a Metro config — usually `getDefaultConfig(__dirname)`
+ * @returns {object} the same config, with uf's extensions, fields and transformer
+ */
+function withUniflowedMetro(config = {}) {
+  const resolver = config.resolver ?? {};
+  const transformer = config.transformer ?? {};
+  const existing = transformer.babelTransformerPath;
+  if (existing != null && existing !== metroTransformerPath) {
+    process.env[configuredUpstreamEnv] = resolveTransformer(existing, config.projectRoot);
+  }
+  return {
+    ...config,
+    resolver: {
+      ...resolver,
+      sourceExts: mergeUnique(resolver.sourceExts, metroSourceExts),
+      resolverMainFields: mergeUnique(resolver.resolverMainFields, metroResolverMainFields),
+      resolveRequest: nativeResolution(resolver.resolveRequest),
+    },
+    transformer: {
+      ...transformer,
+      babelTransformerPath: metroTransformerPath,
+    },
+  };
+}
+
+/**
+ * The absolute path of the transformer a config names.
+ *
+ * An absolute path is taken as given, because that is what Metro does with it.
+ * A package name or a relative path is resolved from the project root, which is
+ * what `getDefaultConfig(projectRoot)` records on the config, and from the
+ * working directory for a config that does not say.
+ */
+function resolveTransformer(specifier, projectRoot) {
+  if (typeof specifier !== "string" || specifier === "") {
+    throw new Error(
+      `@uniflowed/react-native/metro: transformer.babelTransformerPath is ${JSON.stringify(specifier)}, ` +
+        "and the path of a Babel transformer module was expected.",
+    );
+  }
+  if (path.isAbsolute(specifier)) return specifier;
+  const from = typeof projectRoot === "string" ? projectRoot : process.cwd();
+  try {
+    return require.resolve(specifier, { paths: [from] });
+  } catch (error) {
+    throw new Error(
+      `@uniflowed/react-native/metro: transformer.babelTransformerPath names ${specifier}, ` +
+        `which does not resolve from ${from}: ${String(error.message).split("\n")[0]}. ` +
+        "Install it, or name it by its absolute path.",
+    );
+  }
+}
+
+function mergeUnique(existing, required) {
+  const merged = [];
+  const seen = new Set();
+  for (const value of [...(existing ?? []), ...required]) {
+    if (seen.has(value)) continue;
+    seen.add(value);
+    merged.push(value);
+  }
+  return merged;
+}
+
+module.exports = {
+  metroResolverMainFields,
+  metroSourceExts,
+  metroTransformPipeline,
+  metroTransformerPath,
+  nativePackages,
+  withUniflowedMetro,
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@uniflowed/react-native",
+  "version": "0.0.0-alpha.40",
+  "description": "React Native, re-exported for the Unified Toolchain for Flow.",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ubugeeei-prod/uf.git",
+    "directory": "packages/react-native"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./metro": "./metro.cjs",
+    "./metro-transformer.cjs": "./metro-transformer.cjs"
+  },
+  "files": [
+    "index.js",
+    "metro.cjs",
+    "metro-transformer.cjs",
+    "!*.test.js"
+  ],
+  "dependencies": {
+    "@uniflowed/host": "0.0.0-alpha.40"
+  },
+  "peerDependencies": {
+    "react": ">=19.2.3",
+    "react-native": ">=0.86"
+  },
+  "peerDependenciesMeta": {
+    "react-native": {
+      "optional": true
+    }
+  }
+}