@gusnips/native 0.0.0-stage → 0.1.0

package/src/index.ts

@@ -0,0 +1,18 @@
+// @gusnips/native: what a bare React Native app needs beside @gusnips/react.
+//
+// The rule that picks the subpaths is the kit's invariant 15, checked by `bun run exports`: a peer
+// marked optional must not be reachable from this entry. Every subpath below needs one more package
+// with native code or a build tool in it, and an app installs that package only by importing the
+// thing that uses it:
+//
+//   @gusnips/native/theme     createNativeTheme        → @react-native-async-storage/async-storage
+//   @gusnips/native/network   useIsOffline             → @react-native-community/netinfo
+//   @gusnips/native/query     installQueryManagers     → @tanstack/react-query, netinfo
+//   @gusnips/native/i18n      createNativeLanguage     → react-native-localize, async-storage
+//   @gusnips/native/supabase  supabaseAuthStorage      → async-storage, @supabase/supabase-js
+//   @gusnips/native/metro     nativeMetroConfig        → Node, at bundle time
+//   @gusnips/native/css       buildNativeCss           → Node, tailwindcss, react-native-css
+//
+// What is left here needs only the required peers.
+
+export { openSseStream, type SseStream, type SseStreamOptions } from "./sse.ts";

package/src/network.ts

@@ -0,0 +1,37 @@
+/**
+ * Is the phone offline? NetInfo answers, with one rule both helpers here share.
+ *
+ * `isConnected === false` is offline, and nothing else is. NetInfo reports `null` while it has not
+ * worked it out yet, which happens at every launch; reading that as offline puts an offline banner
+ * on screen for the first moment of every session.
+ */
+import NetInfo, { type NetInfoState } from "@react-native-community/netinfo";
+import { useEffect, useState } from "react";
+
+const offline = (state: NetInfoState) => state.isConnected === false;
+
+/**
+ * True while the phone has no connection.
+ *
+ * React Query already pauses on its own once `installQueryManagers` from `@gusnips/native/query`
+ * is running. This is for a screen that should SAY it is offline instead of showing old data as
+ * if it were current.
+ */
+export function useIsOffline(): boolean {
+  const [isOffline, setIsOffline] = useState(false);
+  useEffect(() => NetInfo.addEventListener((state) => setIsOffline(offline(state))), []);
+  return isOffline;
+}
+
+/**
+ * Was that failure the phone, or the server?
+ *
+ * React Native's `fetch` rejects with the same bare `TypeError` when the server is down and when
+ * the phone has no signal. Ask this before telling somebody the service is having trouble: only a
+ * `false` here means the service is to blame. A NetInfo that cannot answer counts as online, so
+ * the doubt goes to the message that has a retry beside it.
+ */
+export async function isDeviceOffline(): Promise<boolean> {
+  const state = await NetInfo.fetch().catch(() => null);
+  return state !== null && offline(state);
+}

package/src/node/bin/gusnips-native-css.ts

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+/**
+ * gusnips-native-css: `buildNativeCss` from the command line, for an app's `start` script.
+ *
+ * Scoped like every bin in this repo: a bare name belongs to whoever registers it on npm, and
+ * `bunx` would download and run theirs.
+ */
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { buildNativeCss, type PaletteEntry } from "../css.ts";
+
+const HELP = `gusnips-native-css: compile global.css for React Native, before Metro starts.
+
+Usage: gusnips-native-css [options]
+
+  --root <dir>       the app's folder (default: the current folder)
+  --input <file>     the Tailwind entry, from the app's folder (default: global.css)
+  --out <dir>        where stylesheet.ts goes (default: src/generated)
+  --palette <file>   a JSON file naming colours for code that cannot take a className:
+                     { "text": { "light": "text-ink", "dark": "dark:text-ink-dark" } }
+                     writes colors.ts beside stylesheet.ts
+  --rem <px>         pixels per rem (default: 16, as on the web)
+  -h, --help         show this
+
+Run it before Metro, in the same script: "start": "gusnips-native-css && react-native start"
+`;
+
+async function main(): Promise<number> {
+  const { values } = parseArgs({
+    options: {
+      root: { type: "string" },
+      input: { type: "string" },
+      out: { type: "string" },
+      palette: { type: "string" },
+      rem: { type: "string" },
+      help: { type: "boolean", short: "h" },
+    },
+  });
+  if (values.help) {
+    process.stdout.write(HELP);
+    return 0;
+  }
+
+  const root = resolve(values.root ?? ".");
+  const result = await buildNativeCss({
+    root,
+    input: values.input,
+    outDir: values.out,
+    rem: values.rem === undefined ? undefined : Number(values.rem),
+    palette: values.palette === undefined ? undefined : await readPalette(resolve(values.palette)),
+  });
+  console.log(`native css: ${result.classes} classes → ${result.files.join(", ")}`);
+  return 0;
+}
+
+/** The palette file is the app's own, but a typo in it should read as one, not as a crash. */
+async function readPalette(file: string): Promise<Record<string, PaletteEntry>> {
+  const parsed: unknown = JSON.parse(await readFile(file, "utf-8"));
+  const palette: Record<string, PaletteEntry> = {};
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+    throw new Error(`${file} must hold an object of colour names.`);
+  for (const [name, entry] of Object.entries(parsed)) {
+    const light: unknown = entry?.light;
+    const dark: unknown = entry?.dark;
+    if (typeof light !== "string" || typeof dark !== "string")
+      throw new Error(
+        `${file}: "${name}" needs a "light" and a "dark" class, such as ` +
+          '{ "light": "text-ink", "dark": "dark:text-ink-dark" }.',
+      );
+    palette[name] = { light, dark };
+  }
+  return palette;
+}
+
+main().then(
+  (code) => {
+    process.exitCode = code;
+  },
+  (error: unknown) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  },
+);

package/src/node/css.ts

@@ -0,0 +1,246 @@
+/**
+ * Tailwind classes for a bare React Native app, built before Metro starts.
+ *
+ * NativeWind v5 and react-native-css resolve `className` at runtime against a compiled stylesheet.
+ * Their own way of compiling it is a Metro transformer that hands the CSS step to
+ * `@expo/metro-config`'s worker, which needs the `expo` package and its native modules. A bare app
+ * has neither, so this runs the same two Expo-free stages itself:
+ *
+ *   1. the Tailwind v4 CLI compiles the app's `global.css` to plain CSS, finding the classes in the
+ *      app's own files (Tailwind v4 has no `--content` flag; a file outside the app folder needs an
+ *      `@source` line in `global.css`);
+ *   2. react-native-css's compiler turns that CSS into the stylesheet its runtime reads.
+ *
+ * The output is a TypeScript module the app injects at launch with `StyleCollection.inject`.
+ * Editing a `className` hot-reloads as usual; only a change to the CSS or the tokens needs a rebuild,
+ * which is why the build runs in the `start`, `ios` and `android` scripts, before Metro.
+ *
+ * Both tools are resolved from the APP's folder, not from this package: the stylesheet has to be in
+ * the format of the react-native-css the bundle will run, and `global.css` imports `tailwindcss`
+ * from where the app installed it.
+ */
+import { spawnSync } from "node:child_process";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { dirname, join, relative, resolve } from "node:path";
+import type { ReactNativeCssStyleSheet } from "react-native-css/compiler";
+
+type Compiler = typeof import("react-native-css/compiler");
+
+/** A colour code needs where it cannot take a `className`: one utility class per scheme. */
+export interface PaletteEntry {
+  /** A class that paints this colour in light mode, such as `"bg-surface"`. */
+  light: string;
+  /** The same in dark mode, such as `"dark:bg-dark-surface"`. */
+  dark: string;
+}
+
+export interface NativeCssOptions {
+  /** The app's folder. The other paths are read from it. Default: the current folder. */
+  root?: string;
+  /** The Tailwind entry. Default: `global.css`. */
+  input?: string;
+  /** Where `stylesheet.ts` (and `colors.ts`) are written. Default: `src/generated`. */
+  outDir?: string;
+  /**
+   * How many pixels one `rem` is. Default: 16, the web's.
+   *
+   * react-native-css's own default is 14, React Native's root font size, and that silently shrinks
+   * every rem-based size by an eighth: body text from 14 to 12.25 px and `h-12` from 48 to 42 px,
+   * against tokens written for the web. A `:root { font-size }` in the CSS does not fix it
+   * reliably, so the number is passed to the compiler instead.
+   */
+  rem?: number;
+  /**
+   * Hex colours for what cannot take a `className`: an icon's `color`, the navigation theme, the
+   * status bar. Each name maps to a class in each scheme, and `colors.ts` gets the hex those classes
+   * compile to. Read from the stylesheet itself, so a change of tokens cannot restyle the classes
+   * and leave the icons in the old colours, which is what a hand-copied list of hex values did.
+   */
+  palette?: Record<string, PaletteEntry>;
+}
+
+export interface NativeCssResult {
+  /** How many classes the stylesheet holds. */
+  classes: number;
+  /** The files written, as absolute paths. */
+  files: string[];
+}
+
+/**
+ * ```ts
+ * await buildNativeCss(); // global.css → src/generated/stylesheet.ts
+ * ```
+ */
+export async function buildNativeCss(options: NativeCssOptions = {}): Promise<NativeCssResult> {
+  const root = resolve(options.root ?? ".");
+  const input = resolve(root, options.input ?? "global.css");
+  const outDir = resolve(root, options.outDir ?? "src/generated");
+  const rem = options.rem ?? 16;
+  if (!(rem > 0)) throw new Error(`buildNativeCss: rem must be a positive number, not ${rem}.`);
+
+  const fromApp = createRequire(join(root, "package.json"));
+  // Before Tailwind, so a missing react-native-css fails in a moment rather than after a compile.
+  const compiler = loadCompiler(fromApp);
+  const css = await runTailwind(fromApp, root, input);
+  const stylesheet = compiler.compile(css, { inlineRem: rem }).stylesheet();
+  dropUnmappable(stylesheet);
+
+  await mkdir(outDir, { recursive: true });
+  const banner = `// Generated by gusnips-native-css from ${relative(root, input)}. Do not edit: run it again.\n`;
+  const stylesheetFile = join(outDir, "stylesheet.ts");
+  await writeFile(
+    stylesheetFile,
+    `${banner}\nimport type { ReactNativeCssStyleSheet } from "react-native-css/compiler";\n\n` +
+      `export const stylesheet: ReactNativeCssStyleSheet = ${JSON.stringify(stylesheet)};\n`,
+  );
+  const files = [stylesheetFile];
+
+  const { palette } = options;
+  if (palette) {
+    const scheme = (mode: keyof PaletteEntry) =>
+      Object.fromEntries(
+        Object.entries(palette).map(([name, entry]) => [
+          name,
+          colorOf(stylesheet, entry[mode], root),
+        ]),
+      );
+    const colors = { light: scheme("light"), dark: scheme("dark") };
+    const colorsFile = join(outDir, "colors.ts");
+    await writeFile(
+      colorsFile,
+      `${banner}\nexport const COLORS = ${JSON.stringify(colors, null, 2)};\n`,
+    );
+    files.push(colorsFile);
+  }
+
+  return { classes: Array.isArray(stylesheet.s) ? stylesheet.s.length : 0, files };
+}
+
+async function runTailwind(fromApp: NodeRequire, root: string, input: string): Promise<string> {
+  const cli = tailwindCli(fromApp);
+  // Out of the app's tree, so building reads the app and writes only `outDir`. Kept when the
+  // compile fails, because the half-written CSS is the first thing worth reading.
+  const work = await mkdtemp(join(tmpdir(), "gusnips-native-css-"));
+  const out = join(work, "tailwind.css");
+  const run = spawnSync(process.execPath, [cli, "-i", input, "-o", out], {
+    cwd: root,
+    encoding: "utf-8",
+    // The compile takes seconds. A hung CLI with no deadline holds `bun run start` forever.
+    timeout: 120_000,
+  });
+  if (run.error !== undefined) throw new Error(`tailwindcss did not finish: ${run.error.message}`);
+  if (run.status !== 0)
+    throw new Error(
+      `tailwindcss could not compile ${input}` +
+        `${run.stderr ? `:\n${run.stderr.slice(0, 1000)}` : ""}\n(work folder kept at ${work})`,
+    );
+  const css = await readFile(out, "utf-8");
+  await rm(work, { recursive: true, force: true });
+  return css;
+}
+
+function tailwindCli(fromApp: NodeRequire): string {
+  let manifestPath: string;
+  try {
+    manifestPath = fromApp.resolve("@tailwindcss/cli/package.json");
+  } catch {
+    throw new Error(missing("@tailwindcss/cli"));
+  }
+  const manifest: { bin?: string | Record<string, string> } = fromApp(manifestPath);
+  const bin = typeof manifest.bin === "string" ? manifest.bin : manifest.bin?.["tailwindcss"];
+  if (!bin) throw new Error(`@tailwindcss/cli at ${manifestPath} names no tailwindcss bin.`);
+  return join(dirname(manifestPath), bin);
+}
+
+/**
+ * The CommonJS build, on purpose: react-native-css's ES module build imports `debug` by a named
+ * export Node cannot see in a CommonJS package, so it does not load under plain Node (bun forgives
+ * it). `require` loads the build that works under both.
+ */
+function loadCompiler(fromApp: NodeRequire): Compiler {
+  let compiler: Compiler;
+  try {
+    compiler = fromApp("react-native-css/compiler");
+  } catch (error) {
+    if (isNotFound(error)) throw new Error(missing("react-native-css"));
+    throw error;
+  }
+  refuseBrokenLightningcss(fromApp);
+  return compiler;
+}
+
+/**
+ * lightningcss 1.30.2 breaks react-native-css's compiler. react-native-css checks for it and means
+ * to throw, but the check sits inside a `try` whose `catch` is empty, so the throw is swallowed and
+ * the build goes on. This asks the same copy its loader picks: the one under `@expo/metro-config`
+ * first (a peer of react-native-css, so bun installs it), then its own.
+ *
+ * That order is also why a devDependency on lightningcss does not fix it. Pin it with `overrides`
+ * in the root `package.json`, which reaches every copy.
+ */
+function refuseBrokenLightningcss(fromApp: NodeRequire): void {
+  const fromCss = createRequire(fromApp.resolve("react-native-css/package.json"));
+  const candidates: NodeRequire[] = [];
+  try {
+    candidates.push(createRequire(fromCss.resolve("@expo/metro-config/package.json")));
+  } catch {
+    // No expo config beside it: react-native-css loads its own lightningcss.
+  }
+  candidates.push(fromCss);
+  for (const from of candidates) {
+    let version: string;
+    try {
+      const manifest: { version: string } = from("lightningcss/package.json");
+      version = manifest.version;
+    } catch {
+      continue;
+    }
+    if (version === "1.30.2")
+      throw new Error(
+        "lightningcss 1.30.2 breaks react-native-css's compiler. Pin it to 1.30.1 with " +
+          '"overrides": { "lightningcss": "1.30.1" } in the root package.json, or move to a newer one.',
+      );
+    return;
+  }
+}
+
+/**
+ * Tailwind finds class names by reading source as text, so a React Native style key such as
+ * `transform` (an Animated style needs one) becomes a candidate. `transform` IS a Tailwind utility,
+ * so it compiles, but its value cannot map to React Native and comes out `null`, which then fails
+ * the app's typecheck on the generated file. Nobody can use it as a class on a phone, so it is
+ * dropped here rather than banning a JavaScript word from every source file.
+ */
+function dropUnmappable(stylesheet: ReactNativeCssStyleSheet): void {
+  if (!Array.isArray(stylesheet.s)) return;
+  stylesheet.s = stylesheet.s.filter(
+    (entry) => !(Array.isArray(entry) && entry[0] === "transform"),
+  );
+}
+
+function colorOf(stylesheet: ReactNativeCssStyleSheet, className: string, root: string): string {
+  const entry = Array.isArray(stylesheet.s)
+    ? stylesheet.s.find((each) => Array.isArray(each) && each[0] === className)
+    : undefined;
+  const hex = entry ? JSON.stringify(entry[1]).match(/#[0-9a-fA-F]{3,8}\b/)?.[0] : undefined;
+  if (hex === undefined)
+    throw new Error(
+      `No colour for "${className}" in the compiled stylesheet. Tailwind writes only the classes ` +
+        `it finds in the app's files, so put "${className}" in a file under ${root} (a list of ` +
+        "the palette's classes beside the code that reads the colours keeps them found).",
+    );
+  return hex;
+}
+
+function missing(name: string): string {
+  return (
+    `${name} is not installed in the app. gusnips-native-css reads it from the app's own ` +
+    "packages: bun add react-native-css && bun add -d @tailwindcss/cli tailwindcss"
+  );
+}
+
+function isNotFound(error: unknown): boolean {
+  return error instanceof Error && "code" in error && error.code === "MODULE_NOT_FOUND";
+}

package/src/node/metro.test.ts

@@ -0,0 +1,66 @@
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { nativeMetroConfig, type ResolutionContext } from "./metro.ts";
+
+// This package's own folder stands in for the app: react and react-native-css are its
+// devDependencies, so they resolve from here the way they resolve from an app.
+const app = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const fromApp = createRequire(join(app, "package.json"));
+
+const context: ResolutionContext = {
+  resolveRequest: (_context, moduleName) => ({ type: `metro:${moduleName}` }),
+};
+
+describe("nativeMetroConfig", () => {
+  const config = nativeMetroConfig(
+    { projectRoot: app, watchFolders: [app], resolver: { nodeModulesPaths: [] } },
+    { monorepoRoot: "/repo" },
+  );
+  const resolve = (moduleName: string) =>
+    config.resolver?.resolveRequest?.(context, moduleName, "ios");
+
+  it("sends react and its entry points to the app's own copy", () => {
+    expect(resolve("react")).toEqual({ type: "sourceFile", filePath: fromApp.resolve("react") });
+    expect(resolve("react/jsx-runtime")).toEqual({
+      type: "sourceFile",
+      filePath: fromApp.resolve("react/jsx-runtime"),
+    });
+  });
+
+  it("leaves packages that only start with the word to Metro", () => {
+    for (const name of ["react-native", "react-dom", "react-i18next", "reactive"])
+      expect(resolve(name)).toEqual({ type: `metro:${name}` });
+  });
+
+  it("maps react-native-css's trap module to its empty override", () => {
+    const override = join(dirname(fromApp.resolve("react-native-css/metro")), "override.js");
+    expect(resolve("react-native-css-metro-override")).toEqual({
+      type: "sourceFile",
+      filePath: override,
+    });
+  });
+
+  it("points Metro at the monorepo without dropping what the config had", () => {
+    expect(config.watchFolders).toEqual([app, "/repo"]);
+    expect(config.resolver?.nodeModulesPaths).toEqual([
+      join(app, "node_modules"),
+      "/repo/node_modules",
+    ]);
+  });
+
+  it("hands what it does not decide to a resolver already on the config", () => {
+    const chained = nativeMetroConfig({
+      projectRoot: app,
+      resolver: { resolveRequest: (_context, moduleName) => ({ type: `own:${moduleName}` }) },
+    });
+    expect(chained.resolver?.resolveRequest?.(context, "lodash", null)).toEqual({
+      type: "own:lodash",
+    });
+  });
+
+  it("refuses a config with no projectRoot", () => {
+    expect(() => nativeMetroConfig({})).toThrow(/getDefaultConfig/);
+  });
+});

package/src/node/metro.ts

@@ -0,0 +1,143 @@
+/**
+ * The Metro config a bare React Native app needs inside a bun monorepo.
+ *
+ * Three things, each learned by a crash:
+ *
+ * - **Metro does not find workspaces on its own.** `watchFolders` and `nodeModulesPaths` point it at
+ *   the monorepo, so a workspace package that ships TypeScript source resolves like any other.
+ *   (Symlinks and package `exports` are on by default since Metro 0.79 and 0.82.)
+ * - **One React, the app's.** bun's isolated store keeps a spare `react` at its root, and a package
+ *   that forgets to declare react as a peer resolves `react` by walking up to THAT copy. Two Reacts
+ *   in one bundle: the app's own screens render, and that package's hooks crash with "Cannot read
+ *   property 'useMemo' of null". So every `react` and `react/*` import goes to the copy the app
+ *   itself resolves.
+ * - **react-native-css's override module.** `react-native-css/native` re-exports a module named
+ *   `react-native-css-metro-override` that throws on import unless Metro maps it to the package's
+ *   own empty `override.js`. Without the mapping every styled component dies at launch with "Cannot
+ *   read property 'useCssElement' of undefined". `withReactNativeCSS` does map it, and also swaps
+ *   Metro's transformer for one that requires `@expo/metro-config`, which a bare app does not have.
+ *   Only the mapping is taken here; the CSS itself is built ahead of time by `gusnips-native-css`.
+ *   Skipped when the app does not use react-native-css.
+ *
+ * Metro's own types are not imported: this package does not depend on metro, and the few fields read
+ * here are stated below.
+ */
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+
+/** What a resolver hands back to Metro. Only the `sourceFile` form is built here. */
+export type Resolution = { type: "sourceFile"; filePath: string } | { type: string };
+
+/** Metro's `CustomResolver`, narrowed to the part this file reads. */
+export type ResolveRequest = (
+  context: ResolutionContext,
+  moduleName: string,
+  platform: string | null,
+) => Resolution;
+
+export interface ResolutionContext {
+  /** Metro's default resolver, for everything this one does not decide. */
+  readonly resolveRequest: ResolveRequest;
+}
+
+export interface MetroConfigInput {
+  readonly projectRoot?: string;
+  readonly watchFolders?: readonly string[];
+  readonly resolver?: {
+    readonly nodeModulesPaths?: readonly string[];
+    readonly resolveRequest?: ResolveRequest | null;
+  };
+}
+
+export interface NativeMetroOptions {
+  /**
+   * The monorepo's root folder, where the root `package.json` and `node_modules` are. Leave it out
+   * for an app that is not in a monorepo.
+   */
+  monorepoRoot?: string;
+}
+
+/**
+ * Wrap the config `@react-native/metro-config` gives you.
+ *
+ * ```js
+ * // metro.config.js
+ * const { getDefaultConfig } = require("@react-native/metro-config");
+ * const { nativeMetroConfig } = require("@gusnips/native/metro");
+ *
+ * module.exports = nativeMetroConfig(getDefaultConfig(__dirname), {
+ *   monorepoRoot: require("node:path").resolve(__dirname, "../.."),
+ * });
+ * ```
+ *
+ * A resolver already on the config still runs for everything this one does not decide.
+ */
+export function nativeMetroConfig<C extends MetroConfigInput>(
+  config: C,
+  { monorepoRoot }: NativeMetroOptions = {},
+) {
+  const { projectRoot } = config;
+  if (!projectRoot)
+    throw new Error(
+      "nativeMetroConfig: the config has no projectRoot. Pass it the config " +
+        "getDefaultConfig(__dirname) returns, which always sets one.",
+    );
+
+  const fromApp = createRequire(join(projectRoot, "package.json"));
+  const cssOverride = reactNativeCssOverride(fromApp);
+  const next = config.resolver?.resolveRequest ?? null;
+
+  const resolveRequest: ResolveRequest = (context, moduleName, platform) => {
+    if (cssOverride && moduleName.includes("react-native-css-metro-override"))
+      return { type: "sourceFile", filePath: cssOverride };
+    if (isReact(moduleName)) return { type: "sourceFile", filePath: fromApp.resolve(moduleName) };
+    return (next ?? context.resolveRequest)(context, moduleName, platform);
+  };
+
+  const extraRoots = monorepoRoot ? [monorepoRoot] : [];
+  return {
+    ...config,
+    watchFolders: unique([...(config.watchFolders ?? []), ...extraRoots]),
+    resolver: {
+      ...config.resolver,
+      nodeModulesPaths: unique([
+        ...[projectRoot, ...extraRoots].map((root) => join(root, "node_modules")),
+        ...(config.resolver?.nodeModulesPaths ?? []),
+      ]),
+      resolveRequest,
+    },
+  };
+}
+
+/**
+ * `react` and its own entry points, and nothing that merely starts with the word: `react-native`,
+ * `react-dom` and `react-i18next` are packages of their own and resolve the normal way.
+ *
+ * ponytail: only react is forced to one copy, because only react has been seen twice. If another
+ * package turns up twice in a bundle (react-native itself is the likely next), add it here.
+ */
+function isReact(moduleName: string): boolean {
+  return moduleName === "react" || moduleName.startsWith("react/");
+}
+
+/** The app's react-native-css `override.js`, or null when the app has no react-native-css. */
+function reactNativeCssOverride(fromApp: NodeRequire): string | null {
+  let metroEntry: string;
+  try {
+    metroEntry = fromApp.resolve("react-native-css/metro");
+  } catch {
+    return null;
+  }
+  const override = join(dirname(metroEntry), "override.js");
+  if (!existsSync(override))
+    throw new Error(
+      `nativeMetroConfig: react-native-css is installed, but ${override} is not there. This ` +
+        "version keeps its override module somewhere else; @gusnips/native needs updating for it.",
+    );
+  return override;
+}
+
+function unique(paths: readonly string[]): string[] {
+  return [...new Set(paths)];
+}

package/src/query.ts

@@ -0,0 +1,41 @@
+/**
+ * React Query on a phone: "focused" means the app is in the foreground, and "online" means NetInfo
+ * says so. React Query's own defaults read the browser's window and `navigator.onLine`, and a
+ * phone has neither.
+ *
+ * What this changes, so nobody expects more of it: a query's retries wait while the app is in the
+ * background or the phone is offline, and resume after; stale queries run again when the connection
+ * comes back (`refetchOnReconnect`, which `queryDefaults` turns on). It does NOT refetch when the app
+ * returns to the foreground, because `queryDefaults` leaves `refetchOnWindowFocus` off on purpose.
+ * The donor's comment said "refetch on app foreground" over a client where that option was off, so
+ * a screen still mounted from yesterday shows yesterday's data until something else refetches it.
+ * Pass `queryDefaults({ refetchOnWindowFocus: true })` if returning to the app should refresh.
+ */
+import NetInfo from "@react-native-community/netinfo";
+import { focusManager, onlineManager } from "@tanstack/react-query";
+import { AppState } from "react-native";
+
+/**
+ * Call once, before the first query runs, beside where you build the `QueryClient`.
+ *
+ * ```ts
+ * installQueryManagers();
+ * export const queryClient = new QueryClient({ defaultOptions: queryDefaults() });
+ * ```
+ *
+ * The managers are React Query's own singletons, so a second call replaces the first rather than
+ * adding a second listener.
+ */
+export function installQueryManagers(): void {
+  focusManager.setEventListener((setFocused) => {
+    const subscription = AppState.addEventListener("change", (state) =>
+      setFocused(state === "active"),
+    );
+    return () => subscription.remove();
+  });
+  // `!== false`, not `=== true`: NetInfo says `null` until it knows, and paused queries at every
+  // launch would be the price of reading that as offline.
+  onlineManager.setEventListener((setOnline) =>
+    NetInfo.addEventListener((state) => setOnline(state.isConnected !== false)),
+  );
+}