create-backtick-app 0.1.8 → 0.1.9

package/README.md

@@ -49,7 +49,12 @@ Every template has:
 
 ### `react-native`
 
-An Expo app (SDK 57) with the Backtick server beside it in `server/`. `App.tsx` fetches the screen at `/home` and runs it with [`@backtickjs/react-native-client`](https://github.com/backtickjs/backtick/tree/main/packages/react-native-client). The app and the server share a `package.json`, so the server bundles for the React and React Native versions installed there.
+An Expo app (SDK 57) with the Backtick server beside it in `server/`. `App.tsx` fetches the screen at `/home` and runs it with [`@backtickjs/react-native-client`](https://github.com/backtickjs/backtick/tree/main/packages/react-native-client), offering screens what `moduleMap.ts` lists.
+
+Each build of the app sends an id that names the modules it carries, which `app.config.ts` works out from `moduleMap.ts`. The server bundles each screen for that build's modules, with [`@backtickjs/builds`](https://github.com/backtickjs/backtick/tree/main/packages/builds), so a build in users' hands keeps working as the app moves on:
+
+- `npm run register-build` records this code's builds in `builds/`. Run it before a build for the stores, and commit what it writes.
+- On EAS, `eas-build-post-install` fails a preview or production build that isn't registered.
 
 ```sh
 npm start        # then scan the QR code with your phone, in Expo Go

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-backtick-app",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Creates a Backtick app: React Native, React or Solid, with screens from your server on Node or Bun",
   "keywords": [
     "backtick",

package/templates/react/package.json

@@ -11,15 +11,15 @@
     "format:check": "prettier --check --ignore-unknown ."
   },
   "dependencies": {
-    "@backtickjs/bundler": "^0.1.8",
-    "@backtickjs/core": "^0.1.8",
-    "@backtickjs/node-plugin": "^0.1.8",
+    "@backtickjs/bundler": "^0.1.9",
+    "@backtickjs/core": "^0.1.9",
+    "@backtickjs/node-plugin": "^0.1.9",
     "@backtickjs/react": "^19.2.3",
     "typescript": "^6.0.3"
   },
   "devDependencies": {
-    "@backtickjs/prettier-plugin": "^0.1.8",
-    "@backtickjs/tsc": "^0.1.8",
+    "@backtickjs/prettier-plugin": "^0.1.9",
+    "@backtickjs/tsc": "^0.1.9",
     "@types/node": "^25.9.1",
     "prettier": "^3.6.2"
   },

package/templates/react/server/html.ts

@@ -4,7 +4,11 @@ import { createRoot } from "@backtickjs/react/client";
 import type { JSX } from "@backtickjs/react/jsx-runtime";
 
 // The versions of React the page loads, below: what each page is bundled for.
-const packageVersions = { react: "19.2.3", "react-dom": "19.2.3" };
+const modules = {
+  react: "19.2.3",
+  "react/jsx-runtime": "19.2.3",
+  "react-dom/client": "19.2.3",
+};
 
 // Development is only what `npm start` runs, which sets NODE_ENV: any other
 // run, a deploy included, is production.
@@ -28,7 +32,7 @@ const reload = `
 export async function toHtml(element: JSX.Element): Promise<string> {
   const bundle = await bundler.build({
     input: cs`$createRoot(document.getElementById("app")!).render($element)`,
-    packageVersions,
+    modules,
   });
   // In development, a map back to the files you wrote, for the browser's
   // devtools.

package/templates/react-native/App.tsx

@@ -1,7 +1,6 @@
-import { evaluate } from "@backtickjs/react-native-client";
+import { buildIdFrom, evaluate } from "@backtickjs/react-native-client";
 import Constants from "expo-constants";
 import { StatusBar } from "expo-status-bar";
-import * as React from "react";
 import {
   Component,
   type ReactNode,
@@ -10,29 +9,32 @@ import {
   useEffect,
   useState,
 } from "react";
-import * as JSXRuntime from "react/jsx-runtime";
-import * as ReactNative from "react-native";
-import { ActivityIndicator, Text } from "react-native";
-
-// What a screen may require: the packages this app was built with.
-const modules = {
-  react: React,
-  "react/jsx-runtime": JSXRuntime,
-  "react-native": ReactNative,
-};
+import { ActivityIndicator, Platform, Text } from "react-native";
+import { moduleMap } from "./moduleMap";
 
 // Your Backtick server runs on the computer Expo was started from.
 const host = Constants.expoConfig?.hostUri?.split(":")[0] ?? "localhost";
 const server = `http://${host}:3000`;
 
+// This build's id, which names the modules it carries, for the server to
+// bundle screens it can run: see app.config.ts.
+const buildId = buildIdFrom(Constants.expoConfig?.extra, Platform.OS);
+
 // The screen at `path` on your server: its bundle, fetched and run with the
-// app's packages. Your fetch to shape: headers, auth, caching.
+// app's modules. Your fetch to shape: headers, auth, caching.
 async function fetchScreen(path: string): Promise<ReactNode> {
-  const response = await fetch(`${server}${path}`);
+  const response = await fetch(`${server}${path}`, {
+    headers: { "x-build-id": buildId },
+  });
+  if (response.status === 426) {
+    throw new Error(
+      "This version of the app is no longer supported: update it.",
+    );
+  }
   if (!response.ok) {
     throw new Error(`${path} answered ${response.status}.`);
   }
-  return evaluate(await response.text(), modules) as ReactNode;
+  return evaluate(await response.text(), moduleMap) as ReactNode;
 }
 
 export default function App() {

package/templates/react-native/app.config.ts

@@ -0,0 +1,10 @@
+import { buildIds } from "@backtickjs/builds";
+import type { ConfigContext, ExpoConfig } from "expo/config";
+
+// app.json, with this build's id on each platform: it names the modules the
+// build carries, which the app sends and the server bundles screens for.
+export default ({ config, projectRoot }: ConfigContext): ExpoConfig =>
+  ({
+    ...config,
+    extra: { ...config.extra, buildIds: buildIds(projectRoot) },
+  }) as ExpoConfig;

package/templates/react-native/moduleMap.ts

@@ -0,0 +1,12 @@
+import type { ModuleMap } from "@backtickjs/react-native-client";
+
+// What a screen may require, and where each comes from: the packages this
+// app is built with. Add one when a screen uses another package. A table and
+// nothing else: the server reads it, without running it, to know what each
+// build of your app carries. A platform that differs gets its own file, as
+// Metro picks files: moduleMap.web.ts, moduleMap.ios.ts.
+export const moduleMap = {
+  react: () => require("react"),
+  "react/jsx-runtime": () => require("react/jsx-runtime"),
+  "react-native": () => require("react-native"),
+} satisfies ModuleMap;

package/templates/react-native/package.json

@@ -11,16 +11,19 @@
     "typecheck": "tsc --noEmit && backtick-tsc -p server --noEmit",
     "test": "node --import ./server/test/setup.mjs --import @backtickjs/node-plugin --test \"server/**/*.test.tsx\"",
     "reset-project": "node scripts/reset-project.mjs",
+    "register-build": "backtick-builds register",
+    "eas-build-post-install": "backtick-builds check",
     "format": "prettier --write --ignore-unknown .",
     "format:check": "prettier --check --ignore-unknown ."
   },
   "dependencies": {
-    "@backtickjs/bundler": "^0.1.8",
-    "@backtickjs/core": "^0.1.8",
-    "@backtickjs/node-plugin": "^0.1.8",
+    "@backtickjs/builds": "^0.1.9",
+    "@backtickjs/bundler": "^0.1.9",
+    "@backtickjs/core": "^0.1.9",
+    "@backtickjs/node-plugin": "^0.1.9",
     "@backtickjs/react": "^19.2.3",
     "@backtickjs/react-native": "^0.86.3",
-    "@backtickjs/react-native-client": "^0.1.8",
+    "@backtickjs/react-native-client": "^0.1.9",
     "expo": "~57.0.26",
     "expo-constants": "~57.0.20",
     "expo-status-bar": "~57.0.1",
@@ -31,8 +34,8 @@
     "typescript": "^6.0.3"
   },
   "devDependencies": {
-    "@backtickjs/prettier-plugin": "^0.1.8",
-    "@backtickjs/tsc": "^0.1.8",
+    "@backtickjs/prettier-plugin": "^0.1.9",
+    "@backtickjs/tsc": "^0.1.9",
     "@testing-library/react": "^16.3.3",
     "@testing-library/user-event": "^14.6.7",
     "@types/node": "^25.9.1",

package/templates/react-native/server/index.tsx

@@ -1,5 +1,6 @@
 import { createServer } from "node:http";
-import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { createBuilds, DeprecatedBuild } from "@backtickjs/builds";
 import { bundler } from "@backtickjs/bundler";
 import { Home } from "./Home.js";
 
@@ -10,30 +11,40 @@ import { Home } from "./Home.js";
 const development = process.env.NODE_ENV === "development";
 const run = crypto.randomUUID();
 
-// The versions of React and React Native the app is built with: this
-// project's own, as the app and this server share a package.json. A server
-// for apps of many versions would tell them apart, by their user agent for
-// one, and bundle each for its own.
-const require = createRequire(import.meta.url);
-const packageVersions = {
-  react: require("react/package.json").version,
-  "react-native": require("react-native/package.json").version,
-};
+// Your app's builds: each sends its id, and a screen is bundled for the
+// modules that build carries, from moduleMap.ts. A build in users' hands
+// keeps working as your app moves on, once registered: see builds/.
+const builds = createBuilds({
+  projectRoot: fileURLToPath(new URL("..", import.meta.url)),
+});
 
 const server = createServer(async (request, response) => {
   // `npm run web` serves the app from another origin.
   response.setHeader("access-control-allow-origin", "*");
+  response.setHeader("access-control-allow-headers", "x-build-id");
+  if (request.method === "OPTIONS") {
+    response.end();
+    return;
+  }
   if (development && request.url === "/live") {
     response.end(run);
     return;
   }
   if (request.url === "/home") {
     try {
-      const bundle = await bundler.build({ input: <Home />, packageVersions });
+      const buildId = request.headers["x-build-id"]?.toString() || null;
+      const modules = builds.modulesOf(buildId);
+      const bundle = await bundler.build({ input: <Home />, modules });
       const { code } = bundle.generate({ format: "cjs" });
       response.setHeader("content-type", "text/javascript");
       response.end(code);
     } catch (error) {
+      // A build you retired: the app asks its user to update.
+      if (error instanceof DeprecatedBuild) {
+        response.statusCode = 426;
+        response.end(String(error));
+        return;
+      }
       // Answered rather than crashed on, so the app can show why.
       console.error(error);
       response.statusCode = 500;

package/templates/react-native/server/test/drawScreen.ts

@@ -1,4 +1,5 @@
-import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { createBuilds } from "@backtickjs/builds";
 import { bundler } from "@backtickjs/bundler";
 import type { Spliceable } from "@backtickjs/core";
 import { evaluate } from "@backtickjs/react-native-client";
@@ -6,24 +7,22 @@ import * as React from "react";
 import * as JSXRuntime from "react/jsx-runtime";
 import * as ReactNativeWeb from "react-native-web";
 
-// What the app provides, as `server/index.tsx` and `App.tsx` say, with React
-// Native's web build standing in for React Native. Add a package here when
-// your app provides one.
-const require = createRequire(import.meta.url);
-const packageVersions = {
-  react: require("react/package.json").version,
-  "react-native": require("react-native/package.json").version,
-};
-const modules = {
-  react: React,
-  "react/jsx-runtime": JSXRuntime,
-  "react-native": ReactNativeWeb,
+// What the app's web build provides, as moduleMap.ts says, with React
+// Native's web build standing in for React Native. Add a stand-in here when
+// your module map offers another package.
+const modules = createBuilds({
+  projectRoot: fileURLToPath(new URL("../..", import.meta.url)),
+}).installed("web");
+const moduleMap = {
+  react: () => React,
+  "react/jsx-runtime": () => JSXRuntime,
+  "react-native": () => ReactNativeWeb,
 };
 
 // A screen, bundled as your server bundles it and run as your app runs it,
 // for Testing Library to draw.
 export async function drawScreen(input: Spliceable): Promise<React.ReactNode> {
-  const bundle = await bundler.build({ input, packageVersions });
+  const bundle = await bundler.build({ input, modules });
   const { code } = bundle.generate({ format: "cjs" });
-  return evaluate(code, modules) as React.ReactNode;
+  return evaluate(code, moduleMap) as React.ReactNode;
 }

package/templates/react-native/server/tsconfig.json

@@ -13,5 +13,6 @@
     "jsx": "react-jsx",
     "jsxImportSource": "@backtickjs/react"
   },
-  "include": ["."]
+  // with app.config.ts, which runs in Node as the server does
+  "include": [".", "../app.config.ts"]
 }

package/templates/react-native/tsconfig.json

@@ -3,5 +3,5 @@
   "compilerOptions": {
     "strict": true
   },
-  "exclude": ["server"]
+  "exclude": ["server", "app.config.ts"]
 }

package/templates/solid-js/package.json

@@ -11,15 +11,15 @@
     "format:check": "prettier --check --ignore-unknown ."
   },
   "dependencies": {
-    "@backtickjs/bundler": "^0.1.8",
-    "@backtickjs/core": "^0.1.8",
-    "@backtickjs/node-plugin": "^0.1.8",
+    "@backtickjs/bundler": "^0.1.9",
+    "@backtickjs/core": "^0.1.9",
+    "@backtickjs/node-plugin": "^0.1.9",
     "@backtickjs/solid-js": "^1.9.14",
     "typescript": "^6.0.3"
   },
   "devDependencies": {
-    "@backtickjs/prettier-plugin": "^0.1.8",
-    "@backtickjs/tsc": "^0.1.8",
+    "@backtickjs/prettier-plugin": "^0.1.9",
+    "@backtickjs/tsc": "^0.1.9",
     "@types/node": "^25.9.1",
     "prettier": "^3.6.2"
   },

package/templates/solid-js/server/html.ts

@@ -4,7 +4,11 @@ import { render } from "@backtickjs/solid-js/web";
 import type { JSX } from "@backtickjs/solid-js/jsx-runtime";
 
 // The version of Solid the page loads, below: what each page is bundled for.
-const packageVersions = { "solid-js": "1.9.14" };
+const modules = {
+  "solid-js": "1.9.14",
+  "solid-js/store": "1.9.14",
+  "solid-js/web": "1.9.14",
+};
 
 // Development is only what `npm start` runs, which sets NODE_ENV: any other
 // run, a deploy included, is production.
@@ -28,7 +32,7 @@ const reload = `
 export async function toHtml(element: JSX.Element): Promise<string> {
   const bundle = await bundler.build({
     input: cs`$render(() => $element, document.getElementById("app")!)`,
-    packageVersions,
+    modules,
   });
   // In development, a map back to the files you wrote, for the browser's
   // devtools.