create-backtick-app 0.1.3 → 0.1.5

package/README.md

@@ -58,10 +58,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 +81,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
@@ -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);
@@ -162,15 +185,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.3",
+  "version": "0.1.5",
   "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.3",
-    "@backtickjs/core": "^0.1.3",
-    "@backtickjs/node-plugin": "^0.1.3",
+    "@backtickjs/bundler": "^0.1.5",
+    "@backtickjs/core": "^0.1.5",
+    "@backtickjs/node-plugin": "^0.1.5",
     "@backtickjs/react": "^19.2.3",
     "typescript": "^6.0.3"
   },
   "devDependencies": {
-    "@backtickjs/prettier-plugin": "^0.1.3",
-    "@backtickjs/tsc": "^0.1.3",
+    "@backtickjs/prettier-plugin": "^0.1.5",
+    "@backtickjs/tsc": "^0.1.5",
     "@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.3",
-    "@backtickjs/core": "^0.1.3",
-    "@backtickjs/node-plugin": "^0.1.3",
+    "@backtickjs/bundler": "^0.1.5",
+    "@backtickjs/core": "^0.1.5",
+    "@backtickjs/node-plugin": "^0.1.5",
     "@backtickjs/react": "^19.2.3",
     "@backtickjs/react-native": "^0.86.3",
-    "@backtickjs/react-native-client": "^0.1.3",
+    "@backtickjs/react-native-client": "^0.1.5",
     "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.3",
-    "@backtickjs/tsc": "^0.1.3",
+    "@backtickjs/prettier-plugin": "^0.1.5",
+    "@backtickjs/tsc": "^0.1.5",
+    "@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.3",
-    "@backtickjs/core": "^0.1.3",
-    "@backtickjs/node-plugin": "^0.1.3",
+    "@backtickjs/bundler": "^0.1.5",
+    "@backtickjs/core": "^0.1.5",
+    "@backtickjs/node-plugin": "^0.1.5",
     "@backtickjs/solid-js": "^1.9.14",
     "typescript": "^6.0.3"
   },
   "devDependencies": {
-    "@backtickjs/prettier-plugin": "^0.1.3",
-    "@backtickjs/tsc": "^0.1.3",
+    "@backtickjs/prettier-plugin": "^0.1.5",
+    "@backtickjs/tsc": "^0.1.5",
     "@types/node": "^25.9.1",
     "prettier": "^3.6.2"
   },