create-backtick-app 0.1.4 → 0.1.6

package/README.md

@@ -1,6 +1,6 @@
 # create-backtick-app
 
-Creates an app whose screens come from your server, with [Backtick](https://backtickjs.com). Pick React Native and you get an Expo app with a Backtick server beside it; pick React or Solid and you get 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 redraws the screen when you save.
 
 ## Usage
 
@@ -17,13 +17,7 @@ yarn create backtick-app
 bun create backtick-app
 ```
 
-It asks only what the command line didn't say:
-
-1. What is your app named? (default `my-app`)
-2. Which framework? `react-native` (an Expo app), `react` or `solid-js` (a web page)
-3. Which runtime? `node` or `bun`: Bun is the default when you ran it with Bun (`bun create`), Node otherwise
-
-It then copies the template into a new directory, installs with the package manager you ran it with (npm, pnpm, Yarn or Bun), and prints the commands to start. Requires Node 22.15 or later.
+It asks for a name, and nothing else: it copies the React Native template into that directory, installs with the package manager you ran it with (npm, pnpm, Yarn or Bun), and prints the commands to start. The server runs on Node, or on Bun when you ran it with Bun (`bun create`). Given the name on the command line, it asks nothing. Requires Node 22.15 or later.
 
 ## Options
 
@@ -31,13 +25,13 @@ It then copies the template into a new directory, installs with the package mana
 npx create-backtick-app@latest [name] [options]
 ```
 
-| Option                  | Description                                                                     |
-| ----------------------- | ------------------------------------------------------------------------------- |
-| `name`                  | The directory to create, and the app's name. It must be new or empty.           |
-| `-t, --template <name>` | `react-native`, `react` or `solid-js`.                                          |
-| `-r, --runtime <name>`  | What runs your Backtick server: `node` or `bun`.                                |
-| `-y, --yes`             | Ask nothing: `my-app`, `react-native`, and Bun if run with Bun, Node otherwise. |
-| `--no-install`          | Copy the files without installing dependencies.                                 |
+| Option                  | Description                                                           |
+| ----------------------- | --------------------------------------------------------------------- |
+| `name`                  | The directory to create, and the app's name. It must be new or empty. |
+| `-t, --template <name>` | `react-native`, the default; or `react` or `solid-js`, a web page.    |
+| `-r, --runtime <name>`  | What runs your Backtick server: `node`, the default, or `bun`.        |
+| `-y, --yes`             | Take `my-app` as the name rather than asking.                         |
+| `--no-install`          | Copy the files without installing dependencies.                       |
 
 With `npm create`, pass options after `--`: `npm create backtick-app@latest my-app -- -t react`.
 
@@ -58,10 +52,13 @@ Every template has:
 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.
 
 ```sh
-npm run ios      # or android, or web
+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.
+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.
+
+`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`
 
@@ -78,7 +75,8 @@ Then open http://localhost:3000. Edit `server/Home.tsx` and save to see the page
 - [`@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
-- [Documentation](https://backtickjs.com/docs)
+- [Quick start](https://backtickjs.com/docs)
+- [Tutorial](https://backtickjs.com/docs/tutorial)
 
 ## License
 

package/dist/index.js

@@ -5,24 +5,40 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
 import prompts from "prompts";
+import { isSupportedNode } from "./nodeVersion.js";
+// The web templates' next steps.
+const webNext = (start) => `To run your project:
+
+${start}
+
+Then open http://localhost:3000. Edit server/Home.tsx and save to see the page change.`;
 const TEMPLATES = {
     "react-native": {
         title: "React Native",
         description: "An Expo app, its screens from your server",
-        scripts: ["android", "ios", "web"],
-        then: "Each starts your Backtick server alongside Expo. Edit server/Home.tsx and save to see the screen change.",
+        next: (start, run) => `To open it on your phone:
+
+1. Install Expo Go on your phone, from the App Store or Google Play.
+2. Connect your phone to the same Wi-Fi network as this computer.
+3. Start your project, which starts your Backtick server alongside Expo:
+
+${start}
+
+4. Scan the QR code it shows: with the Camera app on iPhone, or with Expo Go on Android.
+
+Then edit server/Home.tsx and save to see the screen change on your phone.
+
+No phone at hand? ${run("ios")}, ${run("android")} or ${run("web")} opens it in the iOS Simulator, an Android emulator or a browser instead.`,
     },
     react: {
         title: "React",
         description: "A web page, rendered by React",
-        scripts: ["start"],
-        then: "Then open http://localhost:3000. Edit server/Home.tsx and save to see the page change.",
+        next: webNext,
     },
     "solid-js": {
         title: "solid-js",
         description: "A web page, rendered by Solid",
-        scripts: ["start"],
-        then: "Then open http://localhost:3000. Edit server/Home.tsx and save to see the page change.",
+        next: webNext,
     },
 };
 // What runs your Backtick server, and the loader that compiles it for that
@@ -33,15 +49,15 @@ const RUNTIMES = {
 };
 const USAGE = `Usage: create-backtick-app [name] [options]
 
+Creates a React Native app with a Backtick server beside it, on Node, or on
+Bun when run with Bun.
+
 Options:
   -t, --template <name>  The framework: ${Object.keys(TEMPLATES).join(", ")}
   -r, --runtime <name>   The server's runtime: ${Object.keys(RUNTIMES).join(", ")}
-  -y, --yes              Use the defaults for anything not given
+  -y, --yes              Take my-app as the name rather than asking
   --no-install           Skip installing packages
-  -h, --help             Show this help
-
-Asks for what isn't given, in a terminal; elsewhere, uses the defaults:
-my-app, react-native, and node (bun when run with bun).`;
+  -h, --help             Show this help`;
 let parsed;
 try {
     parsed = parseArgs({
@@ -67,6 +83,13 @@ if (values.help) {
     console.log(USAGE);
     process.exit(0);
 }
+// Said, not refused: what fails on another version is the app's toolchain,
+// later, and only some of it.
+if (!isSupportedNode(process.versions.node)) {
+    console.warn(`Backtick and React Native support Node 22 (22.15 or later) and 24 (24.3 or ` +
+        `later), and you're on Node ${process.versions.node}. If something fails, ` +
+        `switch to Node 22 or 24.\n`);
+}
 if (values.template !== undefined && !(values.template in TEMPLATES)) {
     console.error(`There's no template named ${values.template}. Pick one of: ${Object.keys(TEMPLATES).join(", ")}.`);
     process.exit(1);
@@ -80,41 +103,24 @@ if (values.runtime !== undefined && !(values.runtime in RUNTIMES)) {
 const manager = (process.env.npm_config_user_agent ?? "npm").split("/")[0];
 const run = ["npm", "pnpm", "yarn", "bun"].includes(manager) ? manager : "npm";
 const suggestedRuntime = run === "bun" ? "bun" : "node";
-// Asked only what the command line didn't say, and only in a terminal: an
-// agent or a CI script can't answer, so it gets the defaults, as `--yes` does.
-const ask = process.stdin.isTTY === true && !values.yes;
+// The name is the one question, asked when none was given, and only in a
+// terminal: an agent or a CI script can't answer, so it gets `my-app`, as
+// `--yes` does. The framework and the runtime have defaults, and flags for
+// the rest, as create-expo-app does: a name on the command line is a project
+// with no questions.
+const ask = positionals[0] === undefined && process.stdin.isTTY === true && !values.yes;
 const answers = await prompts([
     {
-        type: positionals[0] !== undefined || !ask ? null : "text",
+        type: ask ? "text" : null,
         name: "name",
         message: "What is your app named?",
         initial: "my-app",
     },
-    {
-        type: values.template !== undefined || !ask ? null : "select",
-        name: "template",
-        message: "Which framework?",
-        choices: Object.entries(TEMPLATES).map(([value, template]) => ({
-            title: template.title,
-            description: template.description,
-            value,
-        })),
-    },
-    {
-        type: values.runtime !== undefined || !ask ? null : "select",
-        name: "runtime",
-        message: "Which runtime?",
-        choices: Object.entries(RUNTIMES).map(([value, runtime]) => ({
-            title: runtime.title,
-            value,
-        })),
-        initial: Object.keys(RUNTIMES).indexOf(suggestedRuntime),
-    },
 ], { onCancel: () => process.exit(1) });
 const name = positionals[0] ?? answers.name ?? "my-app";
-const templateName = values.template ?? answers.template ?? "react-native";
+const templateName = values.template ?? "react-native";
 const template = TEMPLATES[templateName];
-const runtimeName = values.runtime ?? answers.runtime ?? suggestedRuntime;
+const runtimeName = values.runtime ?? suggestedRuntime;
 const target = path.resolve(name);
 const slug = path.basename(target);
 if (existsSync(target) && readdirSync(target).length > 0) {
@@ -162,15 +168,16 @@ if (!values["no-install"]) {
         process.exit(status ?? 1);
     }
 }
+// Created where it was run, there's nowhere to go first.
+const here = target === process.cwd();
+const script = (name) => `${run} run ${name}`;
+const start = [...(here ? [] : [`cd ${slug}`]), script("start")]
+    .map((command) => `   ${command}`)
+    .join("\n");
 console.log(`
 ✅ Your project is ready!
 
-To run your project, navigate to the directory and run one of the following ${run} commands.
-
-- cd ${slug}
-${template.scripts.map((script) => `- ${run} run ${script}`).join("\n")}
-
-${template.then}
+${template.next(start, script)}
 `);
 function rewriteJson(file, change) {
     const json = JSON.parse(readFileSync(file, "utf8"));

package/dist/nodeVersion.d.ts

@@ -0,0 +1 @@
+export declare function isSupportedNode(version: string): boolean;

package/dist/nodeVersion.js

@@ -0,0 +1,7 @@
+// Whether a Node version runs a Backtick project: what React Native 0.86 and
+// Backtick's Node plugin both support, 22.15 and later in 22, 24.3 and later
+// in 24, and 25 on. Node 23 runs neither reliably.
+export function isSupportedNode(version) {
+    const [major = 0, minor = 0] = version.split(".").map(Number);
+    return ((major === 22 && minor >= 15) || (major === 24 && minor >= 3) || major >= 25);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-backtick-app",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "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.4",
-    "@backtickjs/core": "^0.1.4",
-    "@backtickjs/node-plugin": "^0.1.4",
+    "@backtickjs/bundler": "^0.1.6",
+    "@backtickjs/core": "^0.1.6",
+    "@backtickjs/node-plugin": "^0.1.6",
     "@backtickjs/react": "^19.2.3",
     "typescript": "^6.0.3"
   },
   "devDependencies": {
-    "@backtickjs/prettier-plugin": "^0.1.4",
-    "@backtickjs/tsc": "^0.1.4",
+    "@backtickjs/prettier-plugin": "^0.1.6",
+    "@backtickjs/tsc": "^0.1.6",
     "@types/node": "^25.9.1",
     "prettier": "^3.6.2"
   },

package/templates/react-native/package.json

@@ -9,17 +9,18 @@
     "ios": "node scripts/start.mjs --ios",
     "web": "node scripts/start.mjs --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",
     "format": "prettier --write --ignore-unknown .",
     "format:check": "prettier --check --ignore-unknown ."
   },
   "dependencies": {
-    "@backtickjs/bundler": "^0.1.4",
-    "@backtickjs/core": "^0.1.4",
-    "@backtickjs/node-plugin": "^0.1.4",
+    "@backtickjs/bundler": "^0.1.6",
+    "@backtickjs/core": "^0.1.6",
+    "@backtickjs/node-plugin": "^0.1.6",
     "@backtickjs/react": "^19.2.3",
     "@backtickjs/react-native": "^0.86.3",
-    "@backtickjs/react-native-client": "^0.1.4",
+    "@backtickjs/react-native-client": "^0.1.6",
     "expo": "~57.0.26",
     "expo-constants": "~57.0.20",
     "expo-status-bar": "~57.0.1",
@@ -30,10 +31,13 @@
     "typescript": "^6.0.3"
   },
   "devDependencies": {
-    "@backtickjs/prettier-plugin": "^0.1.4",
-    "@backtickjs/tsc": "^0.1.4",
+    "@backtickjs/prettier-plugin": "^0.1.6",
+    "@backtickjs/tsc": "^0.1.6",
+    "@testing-library/react": "^16.3.3",
     "@types/node": "^25.9.1",
     "@types/react": "19.2.18",
+    "global-jsdom": "^30.0.0",
+    "jsdom": "^30.0.1",
     "prettier": "^3.6.2"
   },
   "backtick": {

package/templates/react-native/scripts/reset-project.mjs

@@ -15,6 +15,20 @@ export async function Home() {
 }
 `,
 );
+writeFileSync(
+  "server/Home.test.tsx",
+  `import assert from "node:assert/strict";
+import { it } from "node:test";
+import { render, screen } from "@testing-library/react";
+import { Home } from "./Home.js";
+import { drawScreen } from "./test/drawScreen.js";
+
+it("asks to be edited", async () => {
+  render(await drawScreen(<Home />));
+  assert.ok(screen.getByText("Edit server/Home.tsx to edit this screen."));
+});
+`,
+);
 rmSync("server/HelloWave.tsx", { force: true });
 
 console.log(

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

@@ -4,6 +4,8 @@
 // `--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.
@@ -29,3 +31,27 @@ 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/react-native/server/HelloWave.tsx

@@ -1,11 +1,13 @@
 import { cs } from "@backtickjs/core";
 import { useEffect, useRef } from "@backtickjs/react";
-import { Animated, Pressable } from "@backtickjs/react-native";
+import { Animated, Platform, Pressable } from "@backtickjs/react-native";
 
 // A client component: it runs on the phone, so its animation does too. It
 // waves when it appears, and again when you tap it.
 export const HelloWave = cs`() => {
   const rotation = $useRef(new $Animated.Value(0)).current;
+  // The web has no native animation driver.
+  const nativeDriver = $Platform.OS !== "web";
   const wave = () =>
     $Animated
       .loop(
@@ -13,12 +15,12 @@ export const HelloWave = cs`() => {
           $Animated.timing(rotation, {
             toValue: 1,
             duration: 150,
-            useNativeDriver: true,
+            useNativeDriver: nativeDriver,
           }),
           $Animated.timing(rotation, {
             toValue: 0,
             duration: 150,
-            useNativeDriver: true,
+            useNativeDriver: nativeDriver,
           }),
         ]),
         { iterations: 4 },

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

@@ -0,0 +1,11 @@
+import assert from "node:assert/strict";
+import { it } from "node:test";
+import { render, screen } from "@testing-library/react";
+import { Home } from "./Home.js";
+import { drawScreen } from "./test/drawScreen.js";
+
+it("shows the Node version the server ran", async () => {
+  render(await drawScreen(<Home />));
+  assert.ok(screen.getByText("Welcome!"));
+  assert.ok(screen.getByText(new RegExp(`with Node ${process.version}`)));
+});

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

@@ -0,0 +1,29 @@
+import { createRequire } from "node:module";
+import { bundler } from "@backtickjs/bundler";
+import type { Spliceable } from "@backtickjs/core";
+import { evaluate } from "@backtickjs/react-native-client";
+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,
+};
+
+// 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 { code } = bundle.generate({ format: "cjs" });
+  return evaluate(code, modules) as React.ReactNode;
+}

package/templates/react-native/server/test/react-native-web.d.ts

@@ -0,0 +1,2 @@
+// React Native's web build, which ships no types of its own.
+declare module "react-native-web";

package/templates/react-native/server/test/setup.mjs

@@ -0,0 +1,21 @@
+// What `npm test` runs in: jsdom as the document Testing Library draws into,
+// React told it's under test, and each test's drawing cleared after it.
+import "global-jsdom/register";
+import { cleanup } from "@testing-library/react";
+import { afterEach } from "node:test";
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+afterEach(cleanup);
+
+// jsdom has no ResizeObserver, which React Native's web build looks for as it
+// loads, to report layout.
+window.ResizeObserver ??= class {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+};
+
+// Loaded before `@backtickjs/node-plugin`, so Node loads it as plain
+// CommonJS.
+await import("react-native-web");

package/templates/solid-js/package.json

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