@backtickjs/expo-router 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jean-François Bisson
+
+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

@@ -1,3 +1,9 @@
-# Temporary Holding Version
+# @backtickjs/expo-router
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+expo-router as the Backtick app runs it: the same API and types, with a `Link` that fetches its href ahead while its screen is on top, and as it's pressed, as Next.js's `Link` prefetches every link it shows. The Backtick app serves it as `expo-router`, so apps import `expo-router` as usual and never write `prefetch`.
+
+The fetch is data only: expo-router never preloads a route for it. `prefetch={false}` turns it off. An app sets how a `Link` fetches with `PrefetchContext`; without it, a `Link` is expo-router's.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+import { Link as ExpoLink, router as expoRouter, useRouter as useExpoRouter } from "expo-router";
+import { type ReactNode } from "react";
+export * from "expo-router";
+type Prefetch = (href: string, page: boolean) => void;
+/**
+ * How links and `router.prefetch` under it prefetch, set by the app
+ * serving this module: `prefetch` is the page too.
+ */
+export declare function PrefetchProvider(props: {
+    value: Prefetch;
+    children: ReactNode;
+}): import("react").FunctionComponentElement<import("react").ProviderProps<Prefetch | undefined>>;
+export declare const Link: typeof ExpoLink;
+type Router = typeof expoRouter;
+export declare const router: Router;
+/** expo-router's `useRouter`, whose `prefetch` prefetches for its app. */
+export declare function useRouter(): ReturnType<typeof useExpoRouter>;

package/dist/index.js

@@ -0,0 +1,83 @@
+import { Link as ExpoLink, router as expoRouter, useIsFocused, useRouter as useExpoRouter, } from "expo-router";
+import { resolveHref } from "expo-router/build/link/href";
+import { createContext, createElement, use, useEffect, useMemo, } from "react";
+export * from "expo-router";
+// How a Link fetches its href ahead (with its page, for `prefetch`).
+const PrefetchContext = createContext(undefined);
+// The provider's fetch, which every Link and useRouter needs: the app serving
+// this module always sets one.
+function usePrefetch() {
+    const prefetch = use(PrefetchContext);
+    if (prefetch === undefined) {
+        throw new Error("@backtickjs/expo-router needs a PrefetchProvider above it.");
+    }
+    return prefetch;
+}
+// The fetch of the app on top, for `router.prefetch`, which has no screen.
+let prefetchOnTop;
+/**
+ * How links and `router.prefetch` under it prefetch, set by the app
+ * serving this module: `prefetch` is the page too.
+ */
+export function PrefetchProvider(props) {
+    const focused = useIsFocused();
+    useEffect(() => {
+        if (!focused) {
+            return;
+        }
+        prefetchOnTop = props.value;
+        return () => {
+            if (prefetchOnTop === props.value) {
+                prefetchOnTop = undefined;
+            }
+        };
+    }, [focused, props.value]);
+    return createElement(PrefetchContext, { value: props.value }, props.children);
+}
+// expo-router's Link, which fetches its href ahead while its screen is on
+// top, and again as it's pressed, as Next.js's prefetches every link it
+// shows: what its screen needs to show, and its page too with `prefetch`;
+// `prefetch={false}` turns it off. It never has expo-router preload a route:
+// the fetch is data only.
+function PrefetchingLink({ prefetch, onPressIn, ...props }) {
+    const prefetchHref = usePrefetch();
+    const focused = useIsFocused();
+    const href = resolveHref(props.href);
+    const enabled = prefetch !== false;
+    const page = prefetch === true;
+    useEffect(() => {
+        if (enabled && focused) {
+            prefetchHref(href, page);
+        }
+    }, [enabled, focused, prefetchHref, href, page]);
+    return createElement(ExpoLink, {
+        ...props,
+        onPressIn: (event) => {
+            if (enabled) {
+                prefetchHref(href, page);
+            }
+            onPressIn?.(event);
+        },
+    });
+}
+export const Link = Object.assign(PrefetchingLink, ExpoLink);
+// The router's `prefetch`, as a Link without `prefetch` prefetches: for the
+// app on top, and with none (a moment at startup), nothing. Never a preload.
+const prefetch = (href) => prefetchOnTop?.(resolveHref(href), false);
+// expo-router's router, with that `prefetch`. Read through on each access:
+// expo-router binds the router's methods once it renders.
+export const router = new Proxy(expoRouter, {
+    get(target, key, receiver) {
+        return key === "prefetch" ? prefetch : Reflect.get(target, key, receiver);
+    },
+});
+/** expo-router's `useRouter`, whose `prefetch` prefetches for its app. */
+export function useRouter() {
+    const actions = useExpoRouter();
+    const prefetchHref = usePrefetch();
+    return useMemo(() => ({
+        ...actions,
+        prefetch: (href) => prefetchHref(resolveHref(href), false),
+    }), [actions, prefetchHref]);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@backtickjs/expo-router",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.3.0",
+  "description": "expo-router as the Backtick app runs it: every Link fetches its screen's loading state ahead, as Next.js's does",
+  "keywords": [
+    "backtick",
+    "expo-router",
+    "react-native",
+    "server-driven-ui"
+  ],
+  "homepage": "https://backtickjs.com",
+  "bugs": {
+    "url": "https://github.com/backtickjs/backtick/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/backtickjs/backtick.git",
+    "directory": "packages/expo-router"
+  },
+  "license": "MIT",
+  "author": "Jean-François Bisson <jf@backtickjs.com>",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/._cache",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "expo-router": "~58.0.30",
+    "react": "*"
+  },
+  "devDependencies": {
+    "@types/react": "19.3.0",
+    "expo-router": "~58.0.30",
+    "prettier": "^3.6.2",
+    "react": "19.3.0",
+    "typescript": "^6.0.3"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "tsc -b --watch",
+    "format": "prettier --write --ignore-unknown .",
+    "format:check": "prettier --check --ignore-unknown .",
+    "clean": "rm -rf node_modules dist .turbo"
+  }
 }

package/src/index.ts

@@ -0,0 +1,120 @@
+import {
+  Link as ExpoLink,
+  router as expoRouter,
+  useIsFocused,
+  useRouter as useExpoRouter,
+} from "expo-router";
+import { resolveHref } from "expo-router/build/link/href";
+import {
+  createContext,
+  createElement,
+  type ReactNode,
+  use,
+  useEffect,
+  useMemo,
+} from "react";
+
+export * from "expo-router";
+
+type Prefetch = (href: string, page: boolean) => void;
+
+// How a Link fetches its href ahead (with its page, for `prefetch`).
+const PrefetchContext = createContext<Prefetch | undefined>(undefined);
+
+// The provider's fetch, which every Link and useRouter needs: the app serving
+// this module always sets one.
+function usePrefetch(): Prefetch {
+  const prefetch = use(PrefetchContext);
+  if (prefetch === undefined) {
+    throw new Error(
+      "@backtickjs/expo-router needs a PrefetchProvider above it.",
+    );
+  }
+  return prefetch;
+}
+
+// The fetch of the app on top, for `router.prefetch`, which has no screen.
+let prefetchOnTop: Prefetch | undefined;
+
+/**
+ * How links and `router.prefetch` under it prefetch, set by the app
+ * serving this module: `prefetch` is the page too.
+ */
+export function PrefetchProvider(props: {
+  value: Prefetch;
+  children: ReactNode;
+}) {
+  const focused = useIsFocused();
+  useEffect(() => {
+    if (!focused) {
+      return;
+    }
+    prefetchOnTop = props.value;
+    return () => {
+      if (prefetchOnTop === props.value) {
+        prefetchOnTop = undefined;
+      }
+    };
+  }, [focused, props.value]);
+  return createElement(PrefetchContext, { value: props.value }, props.children);
+}
+
+type LinkProps = Parameters<typeof ExpoLink>[0];
+
+// expo-router's Link, which fetches its href ahead while its screen is on
+// top, and again as it's pressed, as Next.js's prefetches every link it
+// shows: what its screen needs to show, and its page too with `prefetch`;
+// `prefetch={false}` turns it off. It never has expo-router preload a route:
+// the fetch is data only.
+function PrefetchingLink({ prefetch, onPressIn, ...props }: LinkProps) {
+  const prefetchHref = usePrefetch();
+  const focused = useIsFocused();
+  const href = resolveHref(props.href);
+  const enabled = prefetch !== false;
+  const page = prefetch === true;
+  useEffect(() => {
+    if (enabled && focused) {
+      prefetchHref(href, page);
+    }
+  }, [enabled, focused, prefetchHref, href, page]);
+  return createElement(ExpoLink, {
+    ...props,
+    onPressIn: (event) => {
+      if (enabled) {
+        prefetchHref(href, page);
+      }
+      onPressIn?.(event);
+    },
+  });
+}
+
+export const Link = Object.assign(PrefetchingLink, ExpoLink) as typeof ExpoLink;
+
+type Router = typeof expoRouter;
+
+// The router's `prefetch`, as a Link without `prefetch` prefetches: for the
+// app on top, and with none (a moment at startup), nothing. Never a preload.
+const prefetch: Router["prefetch"] = (href) =>
+  prefetchOnTop?.(resolveHref(href), false);
+
+// expo-router's router, with that `prefetch`. Read through on each access:
+// expo-router binds the router's methods once it renders.
+export const router: Router = new Proxy(expoRouter, {
+  get(target, key, receiver) {
+    return key === "prefetch" ? prefetch : Reflect.get(target, key, receiver);
+  },
+});
+
+/** expo-router's `useRouter`, whose `prefetch` prefetches for its app. */
+export function useRouter(): ReturnType<typeof useExpoRouter> {
+  const actions = useExpoRouter();
+  const prefetchHref = usePrefetch();
+  return useMemo(
+    () => ({
+      ...actions,
+      prefetch: (href: Parameters<Router["prefetch"]>[0]) =>
+        prefetchHref(resolveHref(href), false),
+    }),
+    [actions, prefetchHref],
+  );
+}