create-backtick-app 0.1.9 → 0.1.11

package/README.md

@@ -1,6 +1,6 @@
 # create-backtick-app
 
-Creates an app whose screens come from your server, with [Backtick](https://backtickjs.com): an Expo app with a Backtick server beside it, or with `--template react` or `--template solid-js`, a web page served by one. Each starts with a welcome screen written as a server component, a small client component, and a development setup that redraws the screen when you save.
+Creates an app whose screens come from your server, with [Backtick](https://backtickjs.com): an Expo app with a Backtick server beside it, or with `--template react` or `--template solid-js`, a web page served by one. Each starts with a welcome screen written as a server component, a small client component, and a development setup that restarts the server when you save.
 
 ## Usage
 
@@ -41,19 +41,20 @@ 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.
-- `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.
+- `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`.
+- `npm start`: starts the server in development with [nodemon](https://nodemon.io), restarting it whenever you save a file under `server/`. In `react-native`, Expo starts beside it.
 - `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.
+- `AGENTS.md`, which `CLAUDE.md` points to: how a coding agent sees the app while it works, with [agent-device](https://github.com/callstackincubator/agent-device)'s MCP tools from `.mcp.json`. In `react-native` they use the app on a phone `adb devices` lists; in `react` and `solid-js`, the page in a browser.
 - Prettier with `@backtickjs/prettier-plugin`, which formats client scripts too, and VS Code recommendations for the Backtick and Prettier extensions.
 
 ### `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), offering screens what `moduleMap.ts` lists.
+An Expo app (SDK 57) with the Backtick server beside it in `server/`. `client/App.tsx` fetches the screen at `/` and runs it with `execRoot` from [`@backtickjs/core/cjs`](https://github.com/backtickjs/backtick/tree/main/packages/core), offering screens what `client/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:
+Each build of the app sends an id that names the modules it carries, which the `@backtickjs/builds/expo` plugin in `app.json` works out from `client/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.
+- The server draws only registered builds, one file each in `builds/`. `npm start` registers this code's builds as Expo starts; `npm run register-build` does it without Expo, as before a build for the stores. Commit what they write.
 - On EAS, `eas-build-post-install` fails a preview or production build that isn't registered.
 
 ```sh
@@ -61,9 +62,9 @@ npm start        # then scan the QR code with your phone, in Expo Go
 npm run ios      # or android, or web: a simulator, an emulator or a browser
 ```
 
-Each starts your Backtick server alongside Expo, in one terminal. Edit `server/Home.tsx` and save: the app fetches the screen again, without rebuilding. Where Expo can't show its QR code, as when an agent runs it, `npm start` prints the `exp://` address to open in Expo Go instead.
+Each starts your Backtick server alongside Expo, in one terminal. Edit `server/Home.tsx` and save: the server restarts, and `scripts/reload-expo.mjs`, which nodemon runs each time it starts the server, reloads the app once the server listens. The app fetches the new screen without rebuilding.
 
-`npm test` draws `server/Home.tsx` as the app would, in `server/Home.test.tsx`; [Testing screens](https://backtickjs.com/docs/testing) explains the test.
+`npm test` draws `server/Home.tsx` as the app would, in `server/Home.test.tsx`; [Testing screens](https://backtickjs.com/docs/testing/) explains the test.
 
 ### `react` and `solid-js`
 
@@ -73,15 +74,14 @@ A web page: the server bundles `server/Home.tsx` into an HTML page at `/`, with
 npm start
 ```
 
-Then open http://localhost:3000. Edit `server/Home.tsx` and save to see the page change.
+Then open http://localhost:3000. Edit `server/Home.tsx`, save, and refresh the page to see it change.
 
 ## Related
 
 - [`@backtickjs/core`](https://github.com/backtickjs/backtick/tree/main/packages/core): the `cs` tag
 - [`@backtickjs/bundler`](https://github.com/backtickjs/backtick/tree/main/packages/bundler): runs server components and writes the bundle
-- [`@backtickjs/react-native-client`](https://github.com/backtickjs/backtick/tree/main/packages/react-native-client): runs a bundle in a React Native app
-- [Quick start](https://backtickjs.com/docs)
-- [Tutorial](https://backtickjs.com/docs/tutorial)
+- [Quick start](https://backtickjs.com/docs/)
+- [Tutorial](https://backtickjs.com/docs/tutorial/)
 
 ## License
 

package/dist/index.js

@@ -140,14 +140,26 @@ cpSync(templateFolder, target, {
 renameSync(path.join(target, "gitignore"), path.join(target, ".gitignore"));
 rewriteJson(path.join(target, "package.json"), (json) => {
     json.name = slug;
-    // The templates ship Node's loader; another runtime gets its own, which is
-    // how `scripts/start.mjs` knows what to run.
+    // The templates ship Node's loader and scripts; another runtime gets its own.
     const loader = RUNTIMES[runtimeName].loader;
     if (!(loader in json.dependencies)) {
         const version = json.dependencies["@backtickjs/node-plugin"];
         delete json.dependencies["@backtickjs/node-plugin"];
         json.dependencies = Object.fromEntries(Object.entries({ ...json.dependencies, [loader]: version }).sort());
     }
+    if (runtimeName === "bun") {
+        const bun = (command) => command
+            .replace("node --enable-source-maps --import @backtickjs/node-plugin", `bun --preload ${loader}`)
+            .replace("node scripts/", "bun scripts/")
+            .replace("npm:server", "bun:server");
+        for (const [name, command] of Object.entries(json.scripts)) {
+            json.scripts[name] = bun(command);
+        }
+        const events = json.nodemonConfig.events ?? {};
+        for (const [name, command] of Object.entries(events)) {
+            events[name] = bun(command);
+        }
+    }
 });
 if (existsSync(path.join(target, "app.json"))) {
     rewriteJson(path.join(target, "app.json"), (json) => {

package/package.json

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

package/templates/react/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "agent-device": {
+      "command": "npx",
+      "args": ["--no", "agent-device", "mcp"]
+    }
+  }
+}

package/templates/react/AGENTS.md

@@ -0,0 +1,7 @@
+# Seeing the page while you work
+
+`npm start` runs the server on http://localhost:3000, which serves the page. The `agent-device` MCP tools, from `.mcp.json`, see and use it in a browser, once `npx agent-device web setup` has installed one; they need Node 24 or later.
+
+The server's output is in the terminal `npm start` runs in.
+
+Saving a file under `server/` restarts the server: open the page again to see the change. What the server keeps in memory starts over.

package/templates/react/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/templates/react/package.json

@@ -4,25 +4,35 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "start": "node scripts/start.mjs",
+    "start": "nodemon --exec \"node --enable-source-maps --import @backtickjs/node-plugin server/index.tsx\"",
     "reset-project": "node scripts/reset-project.mjs",
     "typecheck": "backtick-tsc --noEmit",
     "format": "prettier --write --ignore-unknown .",
     "format:check": "prettier --check --ignore-unknown ."
   },
   "dependencies": {
-    "@backtickjs/bundler": "^0.1.9",
-    "@backtickjs/core": "^0.1.9",
-    "@backtickjs/node-plugin": "^0.1.9",
+    "@backtickjs/bundler": "^0.1.11",
+    "@backtickjs/core": "^0.1.11",
+    "@backtickjs/node-plugin": "^0.1.11",
     "@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.9",
-    "@backtickjs/tsc": "^0.1.9",
+    "@backtickjs/prettier-plugin": "^0.1.11",
+    "@backtickjs/tsc": "^0.1.11",
     "@types/node": "^25.9.1",
+    "agent-device": "^0.21.27",
+    "nodemon": "^3.1.14",
     "prettier": "^3.6.2"
   },
+  "nodemonConfig": {
+    "watch": [
+      "server"
+    ],
+    "ext": "ts,tsx"
+  },
   "backtick": {
     "plugins": [
       "@backtickjs/react/plugin"

package/templates/react/server/Home.tsx

@@ -35,7 +35,7 @@ export async function Home() {
         <section style={styles.step}>
           <h2 style={styles.subtitle}>Step 1: Try it</h2>
           <p style={styles.body}>
-            Edit <b>server/Home.tsx</b> and save. This page redraws on its own.
+            Edit <b>server/Home.tsx</b>, save, and refresh this page.
           </p>
         </section>
 
@@ -56,7 +56,7 @@ export async function Home() {
           </p>
         </section>
 
-        <a style={styles.link} href="https://backtickjs.com/docs">
+        <a style={styles.link} href="https://backtickjs.com/docs/">
           Read the docs →
         </a>
       </main>

package/templates/react/server/html.ts

@@ -10,23 +10,8 @@ const modules = {
   "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.
-export const development = process.env.NODE_ENV === "development";
-
-// In development, what reloads the page whenever the server restarts, as it
-// does when you save.
-const reload = `
-    <script type="module">
-      let run;
-      setInterval(async () => {
-        try {
-          const next = await (await fetch("/live")).text();
-          if (run !== undefined && next !== run) location.reload();
-          run = next;
-        } catch {}
-      }, 1000);
-    </script>`;
+// Development unless NODE_ENV says production, as hosts set it for a deploy.
+const development = process.env.NODE_ENV !== "production";
 
 // A page: the element, bundled for the browser, and React from a CDN.
 export async function toHtml(element: JSX.Element): Promise<string> {
@@ -60,7 +45,6 @@ export async function toHtml(element: JSX.Element): Promise<string> {
   <body style="margin: 0">
     <div id="app"></div>
     <script type="module" src="data:text/javascript,${encodeURIComponent(code)}"></script>
-    ${development ? reload : ""}
   </body>
 </html>`;
 }

package/templates/react/server/index.tsx

@@ -1,33 +1,20 @@
-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";
+import { toHtml } from "./html.js";
 
-// 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();
+const app = new Hono();
 
-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();
+// 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 />)));
+
+// 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/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "agent-device": {
+      "command": "npx",
+      "args": ["--no", "agent-device", "mcp"]
+    }
+  }
+}

package/templates/react-native/AGENTS.md

@@ -0,0 +1,9 @@
+# Seeing the app while you work
+
+`npm start` runs the server on http://localhost:3000, and Expo beside it; the app runs in Expo Go. The `agent-device` MCP tools, from `.mcp.json`, see and use it, once `adb devices` lists the phone: by USB, or Wi-Fi with Wireless debugging paired.
+
+The server's output is in the terminal `npm start` runs in.
+
+Saving a file under `server/` restarts the server, and Expo reloads the app once it's back: what the server keeps in memory starts over.
+
+A change to `client/moduleMap.ts` or the packages makes a new build: the app has to be closed and opened again. Until then, the server answers the open app with `UnknownBuild`.

package/templates/react-native/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/templates/react-native/app.json

@@ -4,6 +4,7 @@
     "slug": "backtick-app",
     "version": "1.0.0",
     "orientation": "portrait",
-    "userInterfaceStyle": "light"
+    "userInterfaceStyle": "light",
+    "plugins": ["@backtickjs/builds/expo"]
   }
 }

package/templates/react-native/client/App.tsx

@@ -0,0 +1,69 @@
+import { buildIdFrom } from "@backtickjs/builds/client";
+import type { Bundle } from "@backtickjs/core";
+import { execRoot } from "@backtickjs/core/cjs";
+import Constants from "expo-constants";
+import { StatusBar } from "expo-status-bar";
+import { type ReactNode, Suspense, use, useState } from "react";
+import { ActivityIndicator, Platform, Text } from "react-native";
+import {
+  ErrorBoundary,
+  type FallbackProps,
+  getErrorMessage,
+} from "react-error-boundary";
+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: `@backtickjs/builds/expo`, in app.json, adds it.
+const buildId = buildIdFrom(Constants.expoConfig?.extra, Platform.OS);
+
+// The screen at `path` on your server: its bundle, fetched and run with the
+// app's modules. Your fetch to shape: headers, auth, caching.
+async function fetchScreen(path: string): Promise<ReactNode> {
+  const response = await fetch(`${server}${path}`, {
+    headers: { "x-build-id": buildId },
+  });
+  if (!response.ok) {
+    throw new Error(`${path} answered ${response.status}.`);
+  }
+  const bundle = (await response.text()) as Bundle<ReactNode>;
+  return execRoot(bundle, moduleMap);
+}
+
+export default function App() {
+  // Held here, which doesn't suspend, so the request outlives the render
+  // that waits for it.
+  const [screen] = useState(() => fetchScreen("/"));
+  // The whole screen, its layout included, comes from the server: see
+  // server/Home.tsx.
+  return (
+    <>
+      <ErrorBoundary FallbackComponent={Failed}>
+        <Suspense fallback={<ActivityIndicator style={{ flex: 1 }} />}>
+          <Screen screen={screen} />
+        </Suspense>
+      </ErrorBoundary>
+      <StatusBar style="auto" />
+    </>
+  );
+}
+
+// What the server sent, once it has: suspending until then, and throwing,
+// for the boundary, a screen that couldn't be fetched or run.
+function Screen({ screen }: { screen: Promise<ReactNode> }) {
+  return use(screen);
+}
+
+// Why the screen couldn't be drawn: the server unreachable, or a screen the
+// app can't run.
+function Failed({ error }: FallbackProps) {
+  return (
+    <Text style={{ margin: 24, marginTop: 96, color: "#b91c1c" }}>
+      {getErrorMessage(error) ?? String(error)}
+      {"\n\n"}Is your Backtick server running? npm start runs it alongside Expo.
+    </Text>
+  );
+}

package/templates/react-native/client/moduleMap.ts

@@ -0,0 +1,14 @@
+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,
+};

package/templates/react-native/package.json

@@ -2,12 +2,13 @@
   "name": "backtick-app-react-native",
   "version": "1.0.0",
   "private": true,
-  "main": "index.ts",
+  "main": "client/index.ts",
   "scripts": {
-    "start": "node scripts/start.mjs",
-    "android": "node scripts/start.mjs --android",
-    "ios": "node scripts/start.mjs --ios",
-    "web": "node scripts/start.mjs --web",
+    "server": "nodemon --exec \"node --enable-source-maps --import @backtickjs/node-plugin server/index.tsx\"",
+    "start": "concurrently --raw --kill-others npm:server \"expo start\"",
+    "android": "concurrently --raw --kill-others npm:server \"expo start --android\"",
+    "ios": "concurrently --raw --kill-others npm:server \"expo start --ios\"",
+    "web": "concurrently --raw --kill-others npm:server \"expo start --web\"",
     "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",
@@ -17,34 +18,49 @@
     "format:check": "prettier --check --ignore-unknown ."
   },
   "dependencies": {
-    "@backtickjs/builds": "^0.1.9",
-    "@backtickjs/bundler": "^0.1.9",
-    "@backtickjs/core": "^0.1.9",
-    "@backtickjs/node-plugin": "^0.1.9",
+    "@backtickjs/builds": "^0.1.11",
+    "@backtickjs/bundler": "^0.1.11",
+    "@backtickjs/core": "^0.1.11",
+    "@backtickjs/node-plugin": "^0.1.11",
     "@backtickjs/react": "^19.2.3",
     "@backtickjs/react-native": "^0.86.3",
-    "@backtickjs/react-native-client": "^0.1.9",
+    "@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-error-boundary": "6.1.6",
     "react-native": "0.86.3",
     "react-native-web": "^0.21.0",
     "typescript": "^6.0.3"
   },
   "devDependencies": {
-    "@backtickjs/prettier-plugin": "^0.1.9",
-    "@backtickjs/tsc": "^0.1.9",
+    "@backtickjs/prettier-plugin": "^0.1.11",
+    "@backtickjs/tsc": "^0.1.11",
     "@testing-library/react": "^16.3.3",
     "@testing-library/user-event": "^14.6.7",
     "@types/node": "^25.9.1",
     "@types/react": "19.2.18",
+    "agent-device": "^0.21.27",
+    "concurrently": "^10.0.6",
     "global-jsdom": "^30.0.0",
     "jsdom": "^30.0.1",
+    "nodemon": "^3.1.14",
     "prettier": "^3.6.2"
   },
+  "nodemonConfig": {
+    "watch": [
+      "server"
+    ],
+    "ext": "ts,tsx",
+    "events": {
+      "start": "node scripts/reload-expo.mjs"
+    }
+  },
   "backtick": {
+    "clientRoot": "client",
     "plugins": [
       "@backtickjs/react/plugin"
     ]

package/templates/react-native/scripts/reload-expo.mjs

@@ -0,0 +1,37 @@
+// Run by nodemon each time it starts your server: once the server listens,
+// the apps Expo serves reload, as pressing `r` in Expo's terminal does: a
+// `reload` on its message socket, which it accepts from this computer.
+// Nothing happens without Expo running.
+import { connect } from "node:net";
+import { setTimeout as sleep } from "node:timers/promises";
+
+// Your server's port, and Expo's: React Native's variable for it.
+const port = 3000;
+const metro = `ws://127.0.0.1:${process.env.RCT_METRO_PORT ?? 8081}/message`;
+
+// A connection, not a request, so the server has nothing to answer or log.
+const listening = () =>
+  new Promise((resolve) => {
+    const socket = connect(port, "localhost");
+    socket.on("connect", () => {
+      socket.end();
+      resolve(true);
+    });
+    socket.on("error", () => resolve(false));
+  });
+
+// Waited for, so the app doesn't fetch from a server still starting; given up
+// on when it crashed instead.
+for (let tries = 0; tries < 120; tries++) {
+  if (await listening()) {
+    const socket = new WebSocket(metro);
+    socket.onopen = () => {
+      socket.send(JSON.stringify({ version: 2, method: "reload" }));
+      socket.close();
+    };
+    // Expo isn't running: there's no app to reload.
+    socket.onerror = () => {};
+    break;
+  }
+  await sleep(250);
+}

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

@@ -49,8 +49,8 @@ export async function Home() {
         <$View style={styles.step}>
           <$Text style={styles.subtitle}>Step 1: Try it</$Text>
           <$Text style={styles.body}>
-            Edit <$Text style={styles.code}>server/Home.tsx</$Text> and save.
-            This screen redraws without rebuilding the app.
+            Edit <$Text style={styles.code}>server/Home.tsx</$Text>, save, and
+            reload the app. This screen changes without rebuilding it.
           </$Text>
         </$View>
 
@@ -74,7 +74,7 @@ export async function Home() {
 
         <$Text
           style={styles.link}
-          onPress={() => $Linking.openURL("https://backtickjs.com/docs")}
+          onPress={() => $Linking.openURL("https://backtickjs.com/docs/")}
         >
           Read the docs →
         </$Text>

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

@@ -1,61 +1,24 @@
-import { createServer } from "node:http";
-import { fileURLToPath } from "node:url";
-import { createBuilds, DeprecatedBuild } from "@backtickjs/builds";
-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";
 
-// 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();
+const app = new Hono();
 
-// 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)),
-});
+// `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 />));
 
-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 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;
-      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,23 @@
+import { fileURLToPath } from "node:url";
+import { createBuilds } from "@backtickjs/builds";
+import { bundler } from "@backtickjs/bundler";
+import type { JSX } from "@backtickjs/react/jsx-runtime";
+import type { Context } from "hono";
+
+// Your app's builds: each sends its id, and a screen is bundled for the
+// modules that build carries, from client/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.
+ */
+export async function screen(context: Context, element: JSX.Element) {
+  const modules = builds.modulesOf(context.req.header("x-build-id") ?? null);
+  const bundle = await bundler.build({ input: element, modules });
+  const { code } = bundle.generate({ format: "cjs" });
+  return context.body(code, 200, { "content-type": "text/javascript" });
+}

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

@@ -2,27 +2,27 @@ 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";
+import { execRoot } from "@backtickjs/core/cjs";
 import * as React from "react";
 import * as JSXRuntime from "react/jsx-runtime";
 import * as ReactNativeWeb from "react-native-web";
 
-// What the app's web build provides, as moduleMap.ts says, with React
+// What the app's web build provides, as client/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,
+  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> {
+export async function drawScreen<T extends Spliceable>(input: T) {
   const bundle = await bundler.build({ input, modules });
   const { code } = bundle.generate({ format: "cjs" });
-  return evaluate(code, moduleMap) as React.ReactNode;
+  return execRoot(code, moduleMap);
 }

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

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

package/templates/react-native/tsconfig.json

@@ -3,5 +3,6 @@
   "compilerOptions": {
     "strict": true
   },
-  "exclude": ["server", "app.config.ts"]
+  // The app; the server, in server/, has its own.
+  "include": ["client"]
 }

package/templates/solid-js/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "agent-device": {
+      "command": "npx",
+      "args": ["--no", "agent-device", "mcp"]
+    }
+  }
+}

package/templates/solid-js/AGENTS.md

@@ -0,0 +1,7 @@
+# Seeing the page while you work
+
+`npm start` runs the server on http://localhost:3000, which serves the page. The `agent-device` MCP tools, from `.mcp.json`, see and use it in a browser, once `npx agent-device web setup` has installed one; they need Node 24 or later.
+
+The server's output is in the terminal `npm start` runs in.
+
+Saving a file under `server/` restarts the server: open the page again to see the change. What the server keeps in memory starts over.

package/templates/solid-js/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/templates/solid-js/package.json

@@ -4,25 +4,35 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "start": "node scripts/start.mjs",
+    "start": "nodemon --exec \"node --enable-source-maps --import @backtickjs/node-plugin server/index.tsx\"",
     "reset-project": "node scripts/reset-project.mjs",
     "typecheck": "backtick-tsc --noEmit",
     "format": "prettier --write --ignore-unknown .",
     "format:check": "prettier --check --ignore-unknown ."
   },
   "dependencies": {
-    "@backtickjs/bundler": "^0.1.9",
-    "@backtickjs/core": "^0.1.9",
-    "@backtickjs/node-plugin": "^0.1.9",
+    "@backtickjs/bundler": "^0.1.11",
+    "@backtickjs/core": "^0.1.11",
+    "@backtickjs/node-plugin": "^0.1.11",
     "@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.9",
-    "@backtickjs/tsc": "^0.1.9",
+    "@backtickjs/prettier-plugin": "^0.1.11",
+    "@backtickjs/tsc": "^0.1.11",
     "@types/node": "^25.9.1",
+    "agent-device": "^0.21.27",
+    "nodemon": "^3.1.14",
     "prettier": "^3.6.2"
   },
+  "nodemonConfig": {
+    "watch": [
+      "server"
+    ],
+    "ext": "ts,tsx"
+  },
   "backtick": {
     "plugins": [
       "@backtickjs/solid-js/plugin"

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

@@ -35,7 +35,7 @@ export async function Home() {
         <section style={styles.step}>
           <h2 style={styles.subtitle}>Step 1: Try it</h2>
           <p style={styles.body}>
-            Edit <b>server/Home.tsx</b> and save. This page redraws on its own.
+            Edit <b>server/Home.tsx</b>, save, and refresh this page.
           </p>
         </section>
 
@@ -56,7 +56,7 @@ export async function Home() {
           </p>
         </section>
 
-        <a style={styles.link} href="https://backtickjs.com/docs">
+        <a style={styles.link} href="https://backtickjs.com/docs/">
           Read the docs →
         </a>
       </main>

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

@@ -10,23 +10,8 @@ const modules = {
   "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.
-export const development = process.env.NODE_ENV === "development";
-
-// In development, what reloads the page whenever the server restarts, as it
-// does when you save.
-const reload = `
-    <script type="module">
-      let run;
-      setInterval(async () => {
-        try {
-          const next = await (await fetch("/live")).text();
-          if (run !== undefined && next !== run) location.reload();
-          run = next;
-        } catch {}
-      }, 1000);
-    </script>`;
+// Development unless NODE_ENV says production, as hosts set it for a deploy.
+const development = process.env.NODE_ENV !== "production";
 
 // A page: the element, bundled for the browser, and Solid from a CDN.
 export async function toHtml(element: JSX.Element): Promise<string> {
@@ -60,7 +45,6 @@ export async function toHtml(element: JSX.Element): Promise<string> {
   <body style="margin: 0">
     <div id="app"></div>
     <script type="module" src="data:text/javascript,${encodeURIComponent(code)}"></script>
-    ${development ? reload : ""}
   </body>
 </html>`;
 }

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

@@ -1,33 +1,20 @@
-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";
+import { toHtml } from "./html.js";
 
-// 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();
+const app = new Hono();
 
-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();
+// 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 />)));
+
+// 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/scripts/start.mjs

@@ -1,20 +0,0 @@
-// Starts your Backtick server in development: it restarts whenever a file
-// under `server/` changes, and the page reloads with it. Any other way of
-// running the server, a deploy included, is production.
-import { spawn } from "node:child_process";
-import { readFileSync } from "node:fs";
-
-// The runtime is the one package.json has a Backtick loader for: Bun's, or
-// else Node's.
-const { dependencies } = JSON.parse(readFileSync("package.json", "utf8"));
-const [runtime, ...loader] =
-  "@backtickjs/bun-plugin" in dependencies
-    ? ["bun", "--preload", "@backtickjs/bun-plugin"]
-    : ["node", "--enable-source-maps", "--import", "@backtickjs/node-plugin"];
-
-const server = spawn(runtime, ["--watch", ...loader, "server/index.tsx"], {
-  stdio: "inherit",
-  env: { ...process.env, NODE_ENV: process.env.NODE_ENV ?? "development" },
-});
-
-server.on("exit", (code) => process.exit(code ?? 0));

package/templates/react-native/App.tsx

@@ -1,119 +0,0 @@
-import { buildIdFrom, evaluate } from "@backtickjs/react-native-client";
-import Constants from "expo-constants";
-import { StatusBar } from "expo-status-bar";
-import {
-  Component,
-  type ReactNode,
-  Suspense,
-  use,
-  useEffect,
-  useState,
-} from "react";
-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 modules. Your fetch to shape: headers, auth, caching.
-async function fetchScreen(path: string): Promise<ReactNode> {
-  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(), moduleMap) as ReactNode;
-}
-
-export default function App() {
-  // Held here, which doesn't suspend, so the request outlives the render
-  // that waits for it. Each request is numbered, so a new one also clears an
-  // error the last one showed.
-  const [request, setRequest] = useState(() => ({
-    number: 0,
-    screen: fetchScreen("/home"),
-  }));
-  useEffect(() => {
-    // In development, the screen is fetched again each time the server
-    // restarts, so a change to server/ shows as soon as you save.
-    if (__DEV__) {
-      return onServerRestart(() =>
-        setRequest(({ number }) => ({
-          number: number + 1,
-          screen: fetchScreen("/home"),
-        })),
-      );
-    }
-  }, []);
-  // The whole screen, its layout included, comes from the server: see
-  // server/Home.tsx.
-  return (
-    <>
-      <Boundary key={request.number}>
-        <Suspense fallback={<ActivityIndicator style={{ flex: 1 }} />}>
-          <Screen screen={request.screen} />
-        </Suspense>
-      </Boundary>
-      <StatusBar style="auto" />
-    </>
-  );
-}
-
-// What the server sent, once it has: suspending until then, and throwing,
-// for the boundary, a screen that couldn't be fetched or run.
-function Screen({ screen }: { screen: Promise<ReactNode> }) {
-  return use(screen);
-}
-
-// Calls `restarted` when the server starts a new run: it names each run at
-// `/live`, and a new name is a new run.
-function onServerRestart(restarted: () => void): () => void {
-  let run: string | undefined;
-  const timer = setInterval(async () => {
-    try {
-      const next = await (await fetch(`${server}/live`)).text();
-      if (run !== undefined && next !== run) {
-        restarted();
-      }
-      run = next;
-    } catch {
-      // Restarting: the next tick finds the new run.
-    }
-  }, 1000);
-  return () => clearInterval(timer);
-}
-
-// Why the screen couldn't be drawn: the server unreachable, or a screen the
-// app can't run.
-class Boundary extends Component<{ children: ReactNode }, { error: unknown }> {
-  state = { error: null as unknown };
-
-  static getDerivedStateFromError(error: unknown) {
-    return { error };
-  }
-
-  render() {
-    if (this.state.error === null) {
-      return this.props.children;
-    }
-    return (
-      <Text style={{ margin: 24, marginTop: 96, color: "#b91c1c" }}>
-        {String((this.state.error as Error).message ?? this.state.error)}
-        {"\n\n"}Is your Backtick server running? npm start runs it alongside
-        Expo.
-      </Text>
-    );
-  }
-}

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

@@ -1,10 +0,0 @@
-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

@@ -1,12 +0,0 @@
-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/scripts/start.mjs

@@ -1,57 +0,0 @@
-// Starts your Backtick server in development, then Expo, both in this terminal:
-// Expo keeps its keys and QR code, and the server restarts whenever a file
-// under `server/` changes. Arguments are Expo's, as `npm run ios` passes
-// `--ios`.
-import { spawn } from "node:child_process";
-import { readFileSync } from "node:fs";
-import { networkInterfaces } from "node:os";
-import { setTimeout as sleep } from "node:timers/promises";
-
-// The runtime is the one package.json has a Backtick loader for: Bun's, or
-// else Node's.
-const { dependencies } = JSON.parse(readFileSync("package.json", "utf8"));
-const [runtime, ...loader] =
-  "@backtickjs/bun-plugin" in dependencies
-    ? ["bun", "--preload", "@backtickjs/bun-plugin"]
-    : ["node", "--enable-source-maps", "--import", "@backtickjs/node-plugin"];
-
-const server = spawn(runtime, ["--watch", ...loader, "server/index.tsx"], {
-  stdio: "inherit",
-  env: { ...process.env, NODE_ENV: process.env.NODE_ENV ?? "development" },
-});
-
-// `bunx` where Bun runs this script, as it does where Node isn't installed.
-const npx = process.versions.bun ? "bunx" : "npx";
-const expo = spawn(npx, ["expo", "start", ...process.argv.slice(2)], {
-  stdio: "inherit",
-  shell: process.platform === "win32",
-});
-
-expo.on("exit", (code) => {
-  server.kill();
-  process.exit(code ?? 0);
-});
-
-// 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.
-if (!process.stdout.isTTY) {
-  const args = process.argv.slice(2);
-  const flag = args.findIndex((arg) => arg === "--port" || arg === "-p");
-  const port = flag === -1 ? 8081 : Number(args[flag + 1]);
-  const address = Object.values(networkInterfaces())
-    .flat()
-    .find(
-      (network) => network?.family === "IPv4" && !network.internal,
-    )?.address;
-  while (address !== undefined && expo.exitCode === null) {
-    const status = await fetch(`http://localhost:${port}/status`)
-      .then((response) => response.text())
-      .catch(() => "");
-    if (status === "packager-status:running") {
-      console.log(`\nOpen exp://${address}:${port} in Expo Go.\n`);
-      break;
-    }
-    await sleep(500);
-  }
-}

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

@@ -1,20 +0,0 @@
-// Starts your Backtick server in development: it restarts whenever a file
-// under `server/` changes, and the page reloads with it. Any other way of
-// running the server, a deploy included, is production.
-import { spawn } from "node:child_process";
-import { readFileSync } from "node:fs";
-
-// The runtime is the one package.json has a Backtick loader for: Bun's, or
-// else Node's.
-const { dependencies } = JSON.parse(readFileSync("package.json", "utf8"));
-const [runtime, ...loader] =
-  "@backtickjs/bun-plugin" in dependencies
-    ? ["bun", "--preload", "@backtickjs/bun-plugin"]
-    : ["node", "--enable-source-maps", "--import", "@backtickjs/node-plugin"];
-
-const server = spawn(runtime, ["--watch", ...loader, "server/index.tsx"], {
-  stdio: "inherit",
-  env: { ...process.env, NODE_ENV: process.env.NODE_ENV ?? "development" },
-});
-
-server.on("exit", (code) => process.exit(code ?? 0));