create-backtick-app 0.0.0-stage → 0.1.1

package/templates/react-native/.prettierrc

@@ -0,0 +1,3 @@
+{
+  "plugins": ["@backtickjs/prettier-plugin"]
+}

package/templates/react-native/.vscode/extensions.json

@@ -0,0 +1,6 @@
+{
+  "recommendations": [
+    "backtickjs.backtick-vscode",
+    "esbenp.prettier-vscode"
+  ]
+}

package/templates/react-native/App.tsx

@@ -0,0 +1,117 @@
+import { 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,
+  Suspense,
+  use,
+  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,
+};
+
+// Your Backtick server runs on the computer Expo was started from.
+const host = Constants.expoConfig?.hostUri?.split(":")[0] ?? "localhost";
+const server = `http://${host}:3000`;
+
+// The screen at `path` on your server: its bundle, fetched and run with the
+// app's packages. Your fetch to shape: headers, auth, caching.
+async function fetchScreen(path: string): Promise<ReactNode> {
+  const response = await fetch(`${server}${path}`);
+  if (!response.ok) {
+    throw new Error(`${path} answered ${response.status}.`);
+  }
+  return evaluate(await response.text(), modules) 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.json

@@ -0,0 +1,9 @@
+{
+  "expo": {
+    "name": "backtick-app",
+    "slug": "backtick-app",
+    "version": "1.0.0",
+    "orientation": "portrait",
+    "userInterfaceStyle": "light"
+  }
+}

package/templates/react-native/gitignore

@@ -0,0 +1,41 @@
+# Learn more https://docs.github.com/en/get-started/getting-started-with-git/ignoring-files
+
+# dependencies
+node_modules/
+
+# Expo
+.expo/
+dist/
+web-build/
+expo-env.d.ts
+
+# Native
+.kotlin/
+*.orig.*
+*.jks
+*.p8
+*.p12
+*.key
+*.mobileprovision
+
+# Metro
+.metro-health-check*
+
+# debug
+npm-debug.*
+yarn-debug.*
+yarn-error.*
+
+# macOS
+.DS_Store
+*.pem
+
+# local env files
+.env*.local
+
+# typescript
+*.tsbuildinfo
+
+# generated native folders
+/ios
+/android

package/templates/react-native/index.ts

@@ -0,0 +1,8 @@
+import { registerRootComponent } from "expo";
+
+import App from "./App";
+
+// registerRootComponent calls AppRegistry.registerComponent('main', () => App);
+// It also ensures that whether you load the app in Expo Go or in a native build,
+// the environment is set up appropriately
+registerRootComponent(App);

package/templates/react-native/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "backtick-app-react-native",
+  "version": "1.0.0",
+  "private": true,
+  "main": "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",
+    "typecheck": "tsc --noEmit && backtick-tsc -p server --noEmit",
+    "reset-project": "node scripts/reset-project.mjs",
+    "format": "prettier --write --ignore-unknown .",
+    "format:check": "prettier --check --ignore-unknown ."
+  },
+  "dependencies": {
+    "@backtickjs/bundler": "^0.1.1",
+    "@backtickjs/core": "^0.1.1",
+    "@backtickjs/node-plugin": "^0.1.1",
+    "@backtickjs/react": "^19.2.3",
+    "@backtickjs/react-native": "^0.86.3",
+    "@backtickjs/react-native-client": "^0.1.1",
+    "expo": "~57.0.26",
+    "expo-constants": "~57.0.20",
+    "expo-status-bar": "~57.0.1",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "react-native": "0.86.3",
+    "react-native-web": "^0.21.0",
+    "typescript": "^6.0.3"
+  },
+  "devDependencies": {
+    "@backtickjs/prettier-plugin": "^0.1.1",
+    "@backtickjs/tsc": "^0.1.1",
+    "@types/node": "^25.9.1",
+    "@types/react": "19.2.18",
+    "prettier": "^3.6.2"
+  },
+  "backtick": {
+    "plugins": [
+      "@backtickjs/react/plugin"
+    ]
+  }
+}

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

@@ -0,0 +1,22 @@
+// Replaces the welcome screen with a blank one, so you start fresh.
+import { rmSync, writeFileSync } from "node:fs";
+
+writeFileSync(
+  "server/Home.tsx",
+  `import { cs } from "@backtickjs/core";
+import { Text, View } from "@backtickjs/react-native";
+
+export async function Home() {
+  return cs\`(
+    <$View style={{ flex: 1, justifyContent: "center", alignItems: "center" }}>
+      <$Text>Edit server/Home.tsx to edit this screen.</$Text>
+    </$View>
+  )\`;
+}
+`,
+);
+rmSync("server/HelloWave.tsx", { force: true });
+
+console.log(
+  "✅ Project reset. server/Home.tsx is now a blank screen, and the welcome example is gone.",
+);

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

@@ -0,0 +1,31 @@
+// 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";
+
+// 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);
+});

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

@@ -0,0 +1,51 @@
+import { cs } from "@backtickjs/core";
+import { useEffect, useRef } from "@backtickjs/react";
+import { Animated, 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;
+  const wave = () =>
+    $Animated
+      .loop(
+        $Animated.sequence([
+          $Animated.timing(rotation, {
+            toValue: 1,
+            duration: 150,
+            useNativeDriver: true,
+          }),
+          $Animated.timing(rotation, {
+            toValue: 0,
+            duration: 150,
+            useNativeDriver: true,
+          }),
+        ]),
+        { iterations: 4 },
+      )
+      .start();
+
+  $useEffect(wave, []);
+
+  return (
+    <$Pressable onPress={wave}>
+      <$Animated.Text
+        style={{
+          fontSize: 28,
+          lineHeight: 32,
+          marginTop: -6,
+          transform: [
+            {
+              rotate: rotation.interpolate({
+                inputRange: [0, 1],
+                outputRange: ["0deg", "25deg"],
+              }),
+            },
+          ],
+        }}
+      >
+        👋
+      </$Animated.Text>
+    </$Pressable>
+  );
+}`;

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

@@ -0,0 +1,84 @@
+import { cs } from "@backtickjs/core";
+import {
+  Linking,
+  ScrollView,
+  StatusBar,
+  StyleSheet,
+  Text,
+  View,
+} from "@backtickjs/react-native";
+import { HelloWave } from "./HelloWave.js";
+
+// A server component: it runs on your server for every request, and hands the
+// app its data and its client components.
+export async function Home() {
+  // Read here, on your server, and sent to the phone as plain values.
+  const node = process.version;
+  const assembledAt = new Date().toLocaleTimeString();
+
+  // The whole layout is the screen's, safe areas included: iOS insets a root
+  // scroll view itself, and Android draws under its status bar, so the screen
+  // pads for it.
+  return cs`{
+    const styles = $StyleSheet.create({
+      screen: {
+        padding: 24,
+        paddingTop: ($StatusBar.currentHeight ?? 0) + 24,
+        gap: 24,
+      },
+      titleRow: { flexDirection: "row", alignItems: "center", gap: 8 },
+      title: { fontSize: 32, fontWeight: "bold", lineHeight: 32 },
+      step: { gap: 8 },
+      subtitle: { fontSize: 20, fontWeight: "bold" },
+      body: { fontSize: 16, lineHeight: 24 },
+      code: { fontWeight: "600" },
+      link: { fontSize: 16, lineHeight: 30, color: "#0a7ea4" },
+    });
+
+    return (
+      <$ScrollView
+        contentInsetAdjustmentBehavior="automatic"
+        style={{ backgroundColor: "#fff" }}
+        contentContainerStyle={styles.screen}
+      >
+        <$View style={styles.titleRow}>
+          <$Text style={styles.title}>Welcome!</$Text>
+          <$HelloWave />
+        </$View>
+
+        <$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.
+          </$Text>
+        </$View>
+
+        <$View style={styles.step}>
+          <$Text style={styles.subtitle}>Step 2: Server and client</$Text>
+          <$Text style={styles.body}>
+            Your server assembled this screen with Node {$node} at{" "}
+            {$assembledAt}. The waving hand is a client component: its animation
+            runs on your phone. Tap it.
+          </$Text>
+        </$View>
+
+        <$View style={styles.step}>
+          <$Text style={styles.subtitle}>Step 3: Get a fresh start</$Text>
+          <$Text style={styles.body}>
+            When you're ready, run{" "}
+            <$Text style={styles.code}>npm run reset-project</$Text> for a blank{" "}
+            <$Text style={styles.code}>server/Home.tsx</$Text>.
+          </$Text>
+        </$View>
+
+        <$Text
+          style={styles.link}
+          onPress={() => $Linking.openURL("https://backtickjs.com/docs")}
+        >
+          Read the docs →
+        </$Text>
+      </$ScrollView>
+    );
+  }`;
+}

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

@@ -0,0 +1,50 @@
+import { createServer } from "node:http";
+import { createRequire } from "node:module";
+import { bundler } from "@backtickjs/bundler";
+import { Home } from "./Home.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();
+
+// 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,
+};
+
+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();
+});
+
+server.listen(3000, () => {
+  console.log("Backtick server on http://localhost:3000");
+});

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

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    // Imports kept as written: a name a screen only splices, as `$View`, looks
+    // unused to TypeScript, which would otherwise drop its import.
+    "verbatimModuleSyntax": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "target": "esnext",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": ["node"],
+    "jsx": "react-jsx",
+    "jsxImportSource": "@backtickjs/react"
+  },
+  "include": ["."]
+}

package/templates/react-native/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "expo/tsconfig.base",
+  "compilerOptions": {
+    "strict": true
+  },
+  "exclude": ["server"]
+}

package/templates/solid-js/.prettierignore

@@ -0,0 +1,8 @@
+# Written by the package manager.
+pnpm-lock.yaml
+package-lock.json
+yarn.lock
+bun.lock
+
+# Written the way VS Code writes them, one entry per line.
+.vscode/extensions.json

package/templates/solid-js/.prettierrc

@@ -0,0 +1,3 @@
+{
+  "plugins": ["@backtickjs/prettier-plugin"]
+}

package/templates/solid-js/.vscode/extensions.json

@@ -0,0 +1,6 @@
+{
+  "recommendations": [
+    "backtickjs.backtick-vscode",
+    "esbenp.prettier-vscode"
+  ]
+}

package/templates/solid-js/gitignore

@@ -0,0 +1,16 @@
+# dependencies
+node_modules/
+
+# debug
+npm-debug.*
+yarn-debug.*
+yarn-error.*
+
+# macOS
+.DS_Store
+
+# local env files
+.env*.local
+
+# typescript
+*.tsbuildinfo

package/templates/solid-js/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "backtick-app-solid-js",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "node scripts/start.mjs",
+    "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.1",
+    "@backtickjs/core": "^0.1.1",
+    "@backtickjs/node-plugin": "^0.1.1",
+    "@backtickjs/solid-js": "^1.9.14",
+    "typescript": "^6.0.3"
+  },
+  "devDependencies": {
+    "@backtickjs/prettier-plugin": "^0.1.1",
+    "@backtickjs/tsc": "^0.1.1",
+    "@types/node": "^25.9.1",
+    "prettier": "^3.6.2"
+  },
+  "backtick": {
+    "plugins": [
+      "@backtickjs/solid-js/plugin"
+    ]
+  }
+}

package/templates/solid-js/scripts/reset-project.mjs

@@ -0,0 +1,21 @@
+// Replaces the welcome page with a blank one, so you start fresh.
+import { rmSync, writeFileSync } from "node:fs";
+
+writeFileSync(
+  "server/Home.tsx",
+  `import { cs } from "@backtickjs/core";
+
+export async function Home() {
+  return cs\`(
+    <main style={{ padding: "24px", "font-family": "system-ui, sans-serif" }}>
+      <p>Edit server/Home.tsx to edit this page.</p>
+    </main>
+  )\`;
+}
+`,
+);
+rmSync("server/HelloWave.tsx", { force: true });
+
+console.log(
+  "✅ Project reset. server/Home.tsx is now a blank page, and the welcome example is gone.",
+);

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

@@ -0,0 +1,20 @@
+// 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/solid-js/server/HelloWave.tsx

@@ -0,0 +1,34 @@
+import { cs } from "@backtickjs/core";
+import { onMount } from "@backtickjs/solid-js";
+
+// A client component: it runs in the browser, so its animation does too. It
+// waves when it appears, and again when you click it.
+export const HelloWave = cs`() => {
+  let hand!: HTMLSpanElement;
+  const wave = () => {
+    hand.animate(
+      [
+        { transform: "rotate(0deg)" },
+        { transform: "rotate(25deg)" },
+        { transform: "rotate(0deg)" },
+      ],
+      { duration: 300, iterations: 4 },
+    );
+  };
+
+  $onMount(wave);
+
+  return (
+    <span
+      ref={hand}
+      onClick={wave}
+      style={{
+        display: "inline-block",
+        cursor: "pointer",
+        "font-size": "28px",
+      }}
+    >
+      👋
+    </span>
+  );
+}`;