create-backtick-app 0.1.8 → 0.1.10

package/README.md

@@ -41,7 +41,7 @@ Every template has:
 
 - `server/Home.tsx`: the welcome screen, a server component. It reads values on the server and splices them into a client script.
 - `server/HelloWave.tsx`: a client component, a waving hand animated where the screen runs. Tap or click it.
-- `server/index.tsx`: the Backtick server on http://localhost:3000.
+- `server/index.tsx`: the Backtick server on http://localhost:3000, a [Hono](https://hono.dev) app that runs on Node or Bun. Add a route there for each screen or page; a path can take parameters, as `/stories/:id`.
 - `scripts/start.mjs`: starts the server in development, restarting it whenever you save. The client polls `/live`, which exists only in development, and redraws when the server restarts.
 - `npm run reset-project`: replaces `server/Home.tsx` with a blank screen and removes `HelloWave.tsx`.
 - `npm run typecheck`: runs `backtick-tsc` over the server, scripts and splices included. In `react-native`, it also runs `tsc` over the Expo app.
@@ -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 `/` 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.10",
   "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,17 @@
     "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.10",
+    "@backtickjs/core": "^0.1.10",
+    "@backtickjs/node-plugin": "^0.1.10",
     "@backtickjs/react": "^19.2.3",
+    "@hono/node-server": "^2.1.4",
+    "hono": "^4.13.13",
     "typescript": "^6.0.3"
   },
   "devDependencies": {
-    "@backtickjs/prettier-plugin": "^0.1.8",
-    "@backtickjs/tsc": "^0.1.8",
+    "@backtickjs/prettier-plugin": "^0.1.10",
+    "@backtickjs/tsc": "^0.1.10",
     "@types/node": "^25.9.1",
     "prettier": "^3.6.2"
   },

package/templates/react/scripts/start.mjs

@@ -18,3 +18,9 @@ const server = spawn(runtime, ["--watch", ...loader, "server/index.tsx"], {
 });
 
 server.on("exit", (code) => process.exit(code ?? 0));
+
+// Stopped as a whole: a signal to this script alone, as a task runner sends
+// rather than Ctrl-C to the terminal, stops the server with it.
+for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+  process.on(signal, () => server.kill(signal));
+}

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/server/index.tsx

@@ -1,33 +1,27 @@
-import { createServer } from "node:http";
+import { serve } from "@hono/node-server";
+import { Hono } from "hono";
 import { Home } from "./Home.js";
 import { development, toHtml } from "./html.js";
 
+const app = new Hono();
+
+// Your pages: add a route, and the browser can open it. A path can take
+// parameters, `/stories/:id`, read with `context.req.param("id")`.
+app.get("/", async (context) => context.html(await toHtml(<Home />)));
+
 // In development, this run of the server: `--watch` starts a new one whenever
 // you save, and the page, seeing a new one at `/live`, reloads.
-const run = crypto.randomUUID();
+if (development) {
+  const run = crypto.randomUUID();
+  app.get("/live", (context) => context.text(run));
+}
 
-const server = createServer(async (request, response) => {
-  if (development && request.url === "/live") {
-    response.end(run);
-    return;
-  }
-  if (request.url === "/") {
-    try {
-      const html = await toHtml(<Home />);
-      response.setHeader("content-type", "text/html");
-      response.end(html);
-    } catch (error) {
-      // Answered rather than crashed on, so the browser can show why.
-      console.error(error);
-      response.statusCode = 500;
-      response.end(String(error));
-    }
-    return;
-  }
-  response.statusCode = 404;
-  response.end();
+// Answered rather than crashed on, so the browser can show why.
+app.onError((error, context) => {
+  console.error(error);
+  return context.text(String(error), 500);
 });
 
-server.listen(3000, () => {
+serve({ fetch: app.fetch, port: 3000 }, () => {
   console.log("Backtick server on http://localhost:3000");
 });

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,27 @@ 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.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() {
@@ -41,7 +38,7 @@ export default function App() {
   // error the last one showed.
   const [request, setRequest] = useState(() => ({
     number: 0,
-    screen: fetchScreen("/home"),
+    screen: fetchScreen("/"),
   }));
   useEffect(() => {
     // In development, the screen is fetched again each time the server
@@ -50,7 +47,7 @@ export default function App() {
       return onServerRestart(() =>
         setRequest(({ number }) => ({
           number: number + 1,
-          screen: fetchScreen("/home"),
+          screen: fetchScreen("/"),
         })),
       );
     }

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,15 @@
+import type { ModuleMap } from "@backtickjs/react-native-client";
+import * as React from "react";
+import * as JSXRuntime from "react/jsx-runtime";
+import * as ReactNative from "react-native";
+
+// What a screen may require, as your app imports it: the packages it's built
+// with. Add one when a screen uses another package. Imports and a table,
+// 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: React,
+  "react/jsx-runtime": JSXRuntime,
+  "react-native": ReactNative,
+} satisfies ModuleMap;

package/templates/react-native/package.json

@@ -11,19 +11,24 @@
     "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.10",
+    "@backtickjs/bundler": "^0.1.10",
+    "@backtickjs/core": "^0.1.10",
+    "@backtickjs/node-plugin": "^0.1.10",
     "@backtickjs/react": "^19.2.3",
     "@backtickjs/react-native": "^0.86.3",
-    "@backtickjs/react-native-client": "^0.1.8",
+    "@backtickjs/react-native-client": "^0.1.10",
+    "@hono/node-server": "^2.1.4",
     "expo": "~57.0.26",
     "expo-constants": "~57.0.20",
     "expo-status-bar": "~57.0.1",
+    "hono": "^4.13.13",
     "react": "19.2.3",
     "react-dom": "19.2.3",
     "react-native": "0.86.3",
@@ -31,8 +36,8 @@
     "typescript": "^6.0.3"
   },
   "devDependencies": {
-    "@backtickjs/prettier-plugin": "^0.1.8",
-    "@backtickjs/tsc": "^0.1.8",
+    "@backtickjs/prettier-plugin": "^0.1.10",
+    "@backtickjs/tsc": "^0.1.10",
     "@testing-library/react": "^16.3.3",
     "@testing-library/user-event": "^14.6.7",
     "@types/node": "^25.9.1",

package/templates/react-native/scripts/start.mjs

@@ -32,6 +32,15 @@ expo.on("exit", (code) => {
   process.exit(code ?? 0);
 });
 
+// Stopped as a whole: a signal to this script alone, as a task runner sends
+// rather than Ctrl-C to the terminal, stops the server and Expo with it.
+for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+  process.on(signal, () => {
+    server.kill(signal);
+    expo.kill(signal);
+  });
+}
+
 // Expo shows how to open the app, its QR code, only in an interactive
 // terminal. Run elsewhere, as an agent runs it, this prints the address once
 // Metro is up.

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

@@ -0,0 +1,15 @@
+import { cs } from "@backtickjs/core";
+import { Text, View } from "@backtickjs/react-native";
+
+// Every path, for a build you retired: drawn with React Native alone, which
+// every build has, and bundled for the retired build's own modules. Point
+// your users at your store listing here.
+export function AppUpdateRequired() {
+  return cs`(
+    <$View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
+      <$Text style={{ fontSize: 16, textAlign: "center" }}>
+        This version of the app is no longer supported. Update it to keep going.
+      </$Text>
+    </$View>
+  )`;
+}

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

@@ -1,50 +1,33 @@
-import { createServer } from "node:http";
-import { createRequire } from "node:module";
-import { bundler } from "@backtickjs/bundler";
+import { serve } from "@hono/node-server";
+import { Hono } from "hono";
+import { cors } from "hono/cors";
 import { Home } from "./Home.js";
+import { screen } from "./screen.js";
+
+const app = new Hono();
+
+// `npm run web` serves the app from another origin.
+app.use(cors({ origin: "*", allowHeaders: ["x-build-id"] }));
+
+// Your app's screens: add a route, and the app can fetch it. A path can
+// take parameters, `/stories/:id`, read with `context.req.param("id")`.
+app.get("/", (context) => screen(context, <Home />));
 
 // Development is only what `npm start` runs, which sets NODE_ENV: any other
 // run, a deploy included, is production. In development, this run of the
 // server: `--watch` starts a new one whenever you save, and the app, seeing a
 // new one at `/live`, draws its screen again.
-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,
-};
+if (process.env.NODE_ENV === "development") {
+  const run = crypto.randomUUID();
+  app.get("/live", (context) => context.text(run));
+}
 
-const server = createServer(async (request, response) => {
-  // `npm run web` serves the app from another origin.
-  response.setHeader("access-control-allow-origin", "*");
-  if (development && request.url === "/live") {
-    response.end(run);
-    return;
-  }
-  if (request.url === "/home") {
-    try {
-      const bundle = await bundler.build({ input: <Home />, packageVersions });
-      const { code } = bundle.generate({ format: "cjs" });
-      response.setHeader("content-type", "text/javascript");
-      response.end(code);
-    } catch (error) {
-      // Answered rather than crashed on, so the app can show why.
-      console.error(error);
-      response.statusCode = 500;
-      response.end(String(error));
-    }
-    return;
-  }
-  response.statusCode = 404;
-  response.end();
+// Answered rather than crashed on, so the app can show why.
+app.onError((error, context) => {
+  console.error(error);
+  return context.text(String(error), 500);
 });
 
-server.listen(3000, () => {
+serve({ fetch: app.fetch, port: 3000 }, () => {
   console.log("Backtick server on http://localhost:3000");
 });

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

@@ -0,0 +1,33 @@
+import { fileURLToPath } from "node:url";
+import { createBuilds, DeprecatedBuild } from "@backtickjs/builds";
+import { bundler } from "@backtickjs/bundler";
+import type { JSX } from "@backtickjs/react/jsx-runtime";
+import type { Context } from "hono";
+import { AppUpdateRequired } from "./AppUpdateRequired.js";
+
+// 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)),
+});
+
+/**
+ * `element` as the response to a request from your app: bundled for the
+ * modules the requesting build carries, or, for a build you retired, a
+ * screen asking to update, bundled for what it has.
+ */
+export async function screen(context: Context, element: JSX.Element) {
+  let input = element;
+  let modules;
+  try {
+    modules = builds.modulesOf(context.req.header("x-build-id") || null);
+  } catch (error) {
+    if (!(error instanceof DeprecatedBuild)) throw error;
+    input = <AppUpdateRequired />;
+    modules = error.modules;
+  }
+  const bundle = await bundler.build({ input, modules });
+  const { code } = bundle.generate({ format: "cjs" });
+  return context.body(code, 200, { "content-type": "text/javascript" });
+}

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,15 +7,13 @@ 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 = {
+// 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,
@@ -23,7 +22,7 @@ const modules = {
 // 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,17 @@
     "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.10",
+    "@backtickjs/core": "^0.1.10",
+    "@backtickjs/node-plugin": "^0.1.10",
     "@backtickjs/solid-js": "^1.9.14",
+    "@hono/node-server": "^2.1.4",
+    "hono": "^4.13.13",
     "typescript": "^6.0.3"
   },
   "devDependencies": {
-    "@backtickjs/prettier-plugin": "^0.1.8",
-    "@backtickjs/tsc": "^0.1.8",
+    "@backtickjs/prettier-plugin": "^0.1.10",
+    "@backtickjs/tsc": "^0.1.10",
     "@types/node": "^25.9.1",
     "prettier": "^3.6.2"
   },

package/templates/solid-js/scripts/start.mjs

@@ -18,3 +18,9 @@ const server = spawn(runtime, ["--watch", ...loader, "server/index.tsx"], {
 });
 
 server.on("exit", (code) => process.exit(code ?? 0));
+
+// Stopped as a whole: a signal to this script alone, as a task runner sends
+// rather than Ctrl-C to the terminal, stops the server with it.
+for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+  process.on(signal, () => server.kill(signal));
+}

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.

package/templates/solid-js/server/index.tsx

@@ -1,33 +1,27 @@
-import { createServer } from "node:http";
+import { serve } from "@hono/node-server";
+import { Hono } from "hono";
 import { Home } from "./Home.js";
 import { development, toHtml } from "./html.js";
 
+const app = new Hono();
+
+// Your pages: add a route, and the browser can open it. A path can take
+// parameters, `/stories/:id`, read with `context.req.param("id")`.
+app.get("/", async (context) => context.html(await toHtml(<Home />)));
+
 // In development, this run of the server: `--watch` starts a new one whenever
 // you save, and the page, seeing a new one at `/live`, reloads.
-const run = crypto.randomUUID();
+if (development) {
+  const run = crypto.randomUUID();
+  app.get("/live", (context) => context.text(run));
+}
 
-const server = createServer(async (request, response) => {
-  if (development && request.url === "/live") {
-    response.end(run);
-    return;
-  }
-  if (request.url === "/") {
-    try {
-      const html = await toHtml(<Home />);
-      response.setHeader("content-type", "text/html");
-      response.end(html);
-    } catch (error) {
-      // Answered rather than crashed on, so the browser can show why.
-      console.error(error);
-      response.statusCode = 500;
-      response.end(String(error));
-    }
-    return;
-  }
-  response.statusCode = 404;
-  response.end();
+// Answered rather than crashed on, so the browser can show why.
+app.onError((error, context) => {
+  console.error(error);
+  return context.text(String(error), 500);
 });
 
-server.listen(3000, () => {
+serve({ fetch: app.fetch, port: 3000 }, () => {
   console.log("Backtick server on http://localhost:3000");
 });