create-voltapp 0.1.0 → 0.2.0

package/bin/create-voltapp.js

@@ -18,8 +18,9 @@ const here = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8"));
 const TEMPLATES = {
   minimal: "Client app with Vite: signals, JSX, For/Show. No server.",
-  fullstack: "SSR + Vite dev server, router, server functions, live queries, optimistic mutations.",
+  fullstack: "SSR + Vite dev server with HMR, typed router, server functions. The default starter.",
   api: "Server only: Web-standard app with validation, sessions and server functions.",
+  todo: "Full-stack demo: live queries, optimistic mutations, offline queue, cross-tab sync.",
 };
 
 const args = process.argv.slice(2);
@@ -45,7 +46,7 @@ try {
     console.log(`\n${bold("Template")}`);
     const names = Object.keys(TEMPLATES);
     names.forEach((n, i) => console.log(`  ${accent(String(i + 1))}  ${n.padEnd(10)} ${dim(TEMPLATES[n])}`));
-    const answer = (await rl.question(`\nChoose ${dim("(1-3, default 2)")}: `)).trim();
+    const answer = (await rl.question(`\nChoose ${dim("(1-4, default 2)")}: `)).trim();
     template = names[Number(answer) - 1] ?? (names.includes(answer) ? answer : "fullstack");
   }
 } finally {
@@ -77,7 +78,7 @@ const walk = (d) => readdirSync(d).flatMap((f) => (statSync(join(d, f)).isDirect
 for (const file of walk(target)) {
   if (!/\.(json|ts|tsx|html|md|css)$/.test(file)) continue;
   const text = readFileSync(file, "utf8");
-  const next = text.replaceAll("{{name}}", name).replaceAll("{{version}}", pkg.version);
+  const next = text.replaceAll("{{name}}", name).replaceAll("{{version}}", pkg.frameworkVersion ?? pkg.version);
   if (next !== text) writeFileSync(file, next);
 }
 

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "create-voltapp",
-  "version": "0.1.0",
+  "version": "0.2.0",
+  "frameworkVersion": "0.1.0",
   "description": "Scaffold a new Volt app: npm create voltapp@latest my-app",
   "license": "MIT",
   "type": "module",

package/templates/fullstack/README.md

@@ -1,6 +1,6 @@
 # {{name}}
 
-A full-stack Volt app: server-side rendering, a Vite dev server with HMR, typed routing, server functions and live queries with automatic invalidation.
+A Volt app with server-side rendering, a Vite dev server with HMR and typed routing.
 
 ```sh
 npm install
@@ -13,16 +13,21 @@ npm start        # production server
 
 ```
 server.ts                 HTTP server (dev: Vite middleware; prod: dist/)
-src/todos.server.ts       queries and mutations — never shipped to the browser
-src/App.tsx               routes and components
+src/App.tsx               routes: / and /about
+src/Welcome.tsx           starter content — delete it when you begin
 src/entry-client.tsx      render() in the browser
 src/entry-server.tsx      renderToString() for SSR
 ```
 
-## How data flows
+## Add server code
 
-1. `listTodos` is a `query`: while it runs, `todos.read()` records a dependency.
-2. `addTodo` is a `mutation`: `todos.write()` records a change.
-3. The client's `useQuery(listTodos, filter)` refetches whenever a mutation writes `todos`, in every open tab, pushed over `/_volt/live`.
+Create `src/hello.server.ts`:
+
+```ts
+import { serverFn } from "@prouzbek/server/fn";
+export const greet = serverFn(async (name: string) => `Hello, ${name}!`);
+```
+
+Then call `greet("world")` from any component. The file never ships to the browser; the client gets a typed RPC stub. For live queries with automatic invalidation, add `@prouzbek/data` or start from the `todo` template.
 
 Requires Node 24 or newer (TypeScript runs natively).

package/templates/fullstack/package.json

@@ -10,10 +10,8 @@
     "check": "tsc --noEmit"
   },
   "dependencies": {
-    "@prouzbek/data": "{{version}}",
     "@prouzbek/dom": "{{version}}",
     "@prouzbek/router": "{{version}}",
-    "@prouzbek/serialize": "{{version}}",
     "@prouzbek/server": "{{version}}",
     "@prouzbek/signals": "{{version}}"
   },

package/templates/fullstack/server.ts

@@ -4,22 +4,21 @@
  *   npm run build  → client + server bundles in dist/
  *   npm start      → serves dist/ with SSR
  *
- * Server functions (`*.server.ts`) and the live channel are plain middleware.
+ * Server functions (`*.server.ts`) are plain middleware.
  */
 import { createServer } from "node:http";
 import { existsSync, readFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { dirname, extname, join } from "node:path";
 import { createApp, logger } from "@prouzbek/server";
 import { serverFunctions } from "@prouzbek/server/fn";
-import { live } from "@prouzbek/data/server";
 import { toRequest, sendResponse } from "@prouzbek/server/node";
 
 const here = dirname(fileURLToPath(import.meta.url));
 const isProd = process.argv.includes("--prod") || process.env.NODE_ENV === "production";
 const port = Number(process.env.PORT ?? 5173);
 
-const app = createApp().use(logger()).use(live()).use(serverFunctions());
+const app = createApp().use(logger()).use(serverFunctions());
 
 let vite: import("vite").ViteDevServer | undefined;
 let template: string;
@@ -31,7 +30,7 @@ if (!isProd) {
   template = readFileSync(join(here, "index.html"), "utf8");
 } else {
   template = readFileSync(join(here, "dist/client/index.html"), "utf8");
-  renderPage = (await import(join(here, "dist/server/entry-server.js").replace(/\\/g, "/"))).render;
+  renderPage = (await import(pathToFileURL(join(here, "dist/server/entry-server.js")).href)).render;
 }
 
 app.get("*", async (c) => {

package/templates/fullstack/src/App.tsx

@@ -1,14 +1,11 @@
-import { signal } from "@prouzbek/signals";
-import { For, Show } from "@prouzbek/dom";
-import { route, Link, Outlet, useSearchParams, type RouteDef } from "@prouzbek/router";
-import { useQuery, useMutation } from "@prouzbek/data/client";
-import { listTodos, addTodo, toggleTodo, removeTodo, type Filter, type Todo } from "./todos.server.ts";
+import { route, Link, Outlet, type RouteDef } from "@prouzbek/router";
+import { Welcome } from "./Welcome.tsx";
 
 function Layout() {
   return (
     <>
       <nav>
-        <Link href="/" activeClass="active">Todos</Link>
+        <Link href="/" activeClass="active">Home</Link>
         <Link href="/about" activeClass="active">About</Link>
       </nav>
       <Outlet />
@@ -16,79 +13,12 @@ function Layout() {
   );
 }
 
-function Todos() {
-  const [params, setParams] = useSearchParams();
-  const filter = () => (params.value.get("filter") as Filter | null) ?? "all";
-  const list = useQuery(listTodos, filter);
-  const draft = signal("");
-
-  const add = useMutation(addTodo, {
-    optimistic: (cache, title) =>
-      cache.updateAll(listTodos, (cur) => [...cur, { id: -Date.now(), title, done: false, createdAt: new Date() }]),
-  });
-  const toggle = useMutation(toggleTodo, {
-    optimistic: (cache, id) => cache.updateAll(listTodos, (cur) => cur.map((t) => (t.id === id ? { ...t, done: !t.done } : t))),
-  });
-  const remove = useMutation(removeTodo, {
-    optimistic: (cache, id) => cache.updateAll(listTodos, (cur) => cur.filter((t) => t.id !== id)),
-  });
-
-  return (
-    <section>
-      <h1>⚡ {{name}}</h1>
-      <p class="muted">
-        Server-rendered, live-synced todos. Open this page in two tabs.
-        <Show when={add.queued.value > 0}> · {add.queued.value} queued offline</Show>
-      </p>
-      <p class="filters">
-        {(["all", "open", "done"] as Filter[]).map((f) => (
-          <button type="button" disabled={filter() === f} onClick={() => void setParams({ filter: f === "all" ? null : f })}>
-            {f}
-          </button>
-        ))}
-      </p>
-      <form
-        onSubmit={(e) => {
-          e.preventDefault();
-          const title = draft.value;
-          draft.value = "";
-          void add.run(title).catch(() => {});
-        }}
-      >
-        <input value={draft} onInput={(e) => (draft.value = e.currentTarget.value)} placeholder="What needs doing?" />
-        <button type="submit" disabled={!draft.value.trim()}>Add</button>
-      </form>
-      <Show when={add.error.value}>{(err) => <p class="muted">⚠ {String((err.value as Error).message)}</p>}</Show>
-      <Show when={list.data.value} fallback={<p class="muted">Loading…</p>}>
-        <ul>
-          <For each={list.data.value ?? []} fallback={<li class="muted">Nothing here.</li>}>
-            {(todo: Todo) => (
-              <li classList={{ done: todo.done, pending: todo.id < 0 }}>
-                <label>
-                  <input type="checkbox" checked={todo.done} disabled={todo.id < 0} onChange={() => void toggle.run(todo.id)} />
-                  <span>{todo.title}</span>
-                </label>
-                <button class="link" type="button" disabled={todo.id < 0} onClick={() => void remove.run(todo.id)}>
-                  remove
-                </button>
-              </li>
-            )}
-          </For>
-        </ul>
-      </Show>
-    </section>
-  );
-}
-
 function About() {
   return (
-    <section>
+    <main>
       <h1>About</h1>
-      <p>
-        <code>src/todos.server.ts</code> never reaches the browser. The client calls its exports as typed RPC stubs, and
-        every query refetches automatically when a mutation writes the source it read.
-      </p>
-    </section>
+      <p>Routes live in <code>src/App.tsx</code>. Each page is a component; the server renders the first one and the browser takes over from there.</p>
+    </main>
   );
 }
 
@@ -96,6 +26,6 @@ export const routes: RouteDef[] = [
   route({
     path: "/",
     component: Layout,
-    children: [route({ path: "", component: Todos }), route({ path: "about", component: About })],
+    children: [route({ path: "", component: Welcome }), route({ path: "about", component: About })],
   }),
 ];

package/templates/fullstack/src/Welcome.tsx

@@ -0,0 +1,28 @@
+import { signal } from "@prouzbek/signals";
+
+/**
+ * Starter content. Delete this file and its route in App.tsx when you begin.
+ */
+export function Welcome() {
+  const count = signal(0);
+
+  return (
+    <main class="welcome">
+      <a href="https://www.npmjs.com/package/create-voltapp" target="_blank" rel="noreferrer">
+        <svg class="logo" viewBox="0 0 24 24" aria-hidden="true">
+          <path d="M13.5 2 4 14h7l-1.5 8L20 10h-7z" />
+        </svg>
+      </a>
+      <h1>{{name}}</h1>
+      <div class="card">
+        <button type="button" onClick={() => count.value++}>
+          count is {count}
+        </button>
+        <p>
+          Edit <code>src/Welcome.tsx</code> and save to test HMR
+        </p>
+      </div>
+      <p class="muted">This page was rendered on the server, then hydrated. Add a file ending in <code>.server.ts</code> to call server code as typed functions.</p>
+    </main>
+  );
+}

package/templates/fullstack/src/entry-client.tsx

@@ -1,11 +1,8 @@
 import { render } from "@prouzbek/dom";
 import { createRouter, RouterProvider } from "@prouzbek/router";
-import { createQueryClient, provideQueryClient } from "@prouzbek/data/client";
 import { routes } from "./App.tsx";
 
-const client = createQueryClient({ storage: localStorage });
 const router = createRouter(routes);
-
 const root = document.getElementById("app")!;
 root.innerHTML = "";
-render(() => provideQueryClient(client, () => <RouterProvider router={router} />), root);
+render(() => <RouterProvider router={router} />, root);

package/templates/fullstack/src/entry-server.tsx

@@ -1,14 +1,11 @@
 import { renderToString } from "@prouzbek/dom";
 import { createRouter, RouterProvider } from "@prouzbek/router";
-import { createQueryClient, provideQueryClient } from "@prouzbek/data/client";
 import { routes } from "./App.tsx";
 
 export async function render(url: string, request: Request): Promise<string> {
-  const client = createQueryClient({ liveUrl: false });
   const router = createRouter(routes, { url, request });
   await router.ready;
-  const html = renderToString(() => provideQueryClient(client, () => <RouterProvider router={router} />));
-  client.dispose();
+  const html = renderToString(() => <RouterProvider router={router} />);
   router.dispose();
   return html;
 }

package/templates/fullstack/src/styles.css

@@ -1,80 +1,65 @@
 :root {
   color-scheme: light dark;
   font: 16px/1.5 system-ui, sans-serif;
+  --accent: #8b8bff;
   --border: color-mix(in srgb, currentColor 18%, transparent);
 }
 body {
-  max-width: 560px;
-  margin: 2rem auto;
-  padding: 0 1rem;
+  max-width: 640px;
+  margin: 0 auto;
+  padding: 1.5rem 1rem;
 }
 nav {
   display: flex;
   gap: 1rem;
-  margin-bottom: 1.5rem;
 }
 nav a {
   color: inherit;
   opacity: 0.7;
+  text-decoration: none;
 }
 nav a.active {
   opacity: 1;
   font-weight: 600;
-  text-decoration: underline;
 }
-h1 {
-  margin: 0 0 0.25rem;
+main {
+  padding-top: 3rem;
 }
-.muted {
-  opacity: 0.65;
-  font-size: 0.9rem;
+.welcome {
+  text-align: center;
 }
-.filters,
-form {
-  display: flex;
-  gap: 0.5rem;
-  margin: 1rem 0;
+.logo {
+  width: 5rem;
+  height: 5rem;
+  fill: var(--accent);
+  filter: drop-shadow(0 0 1.5rem color-mix(in srgb, var(--accent) 60%, transparent));
 }
-form input {
-  flex: 1;
-  padding: 0.5rem;
-  border: 1px solid var(--border);
-  border-radius: 6px;
-  background: transparent;
-  color: inherit;
+h1 {
+  font-size: 2.5rem;
+  margin: 0.5rem 0 1.5rem;
+}
+.card {
+  display: grid;
+  gap: 1rem;
+  justify-items: center;
+  padding: 2rem;
 }
 button {
-  padding: 0.4rem 0.9rem;
+  padding: 0.6rem 1.2rem;
+  font: inherit;
   border: 1px solid var(--border);
-  border-radius: 999px;
+  border-radius: 8px;
   background: transparent;
   color: inherit;
   cursor: pointer;
 }
-button:disabled {
-  opacity: 0.4;
-  cursor: not-allowed;
-}
-button.link {
-  border: 0;
-  opacity: 0.6;
-  font-size: 0.85rem;
+button:hover {
+  border-color: var(--accent);
 }
-ul {
-  list-style: none;
-  padding: 0;
-  margin: 0;
-}
-li {
-  display: flex;
-  justify-content: space-between;
-  align-items: center;
-  padding: 0.3rem 0;
+code {
+  font-size: 0.9em;
 }
-li.done span {
-  text-decoration: line-through;
-  opacity: 0.6;
-}
-li.pending {
-  opacity: 0.5;
+.muted {
+  opacity: 0.65;
+  font-size: 0.9rem;
 }

package/templates/fullstack/vite.config.ts

@@ -5,5 +5,5 @@ export default defineConfig({
   plugins: [volt()],
   appType: "custom",
   server: { middlewareMode: true },
-  build: { manifest: true, rollupOptions: { input: "/src/entry-client.tsx" } },
+  build: { manifest: true },
 });

package/templates/minimal/README.md

@@ -8,6 +8,6 @@ npm run dev      # http://localhost:5173
 npm run build    # production build in dist/
 ```
 
-- `src/main.tsx` is the whole app. Components run once; signals drive updates.
+- `src/main.tsx` is the whole app. Components run once; signals drive updates. Replace the `App` component to begin.
 - `For`, `Show` and friends come from `@prouzbek/dom`; `signal`/`computed` from `@prouzbek/signals`.
-- Need a server, routing or live data? Scaffold the `fullstack` template: `npm create voltapp@latest -- --template fullstack`.
+- Need SSR and routing? Scaffold the `fullstack` template. Want to see live queries? Try `todo`: `npm create voltapp@latest -- --template todo`.

package/templates/minimal/src/main.tsx

@@ -1,74 +1,27 @@
-import { signal, computed } from "@prouzbek/signals";
-import { render, For, Show } from "@prouzbek/dom";
+import { signal } from "@prouzbek/signals";
+import { render } from "@prouzbek/dom";
 import "./styles.css";
 
-type Item = { id: number; text: string; done: boolean };
-
 function App() {
   const count = signal(0);
-  const double = computed(() => count.value * 2);
-
-  const items = signal<Item[]>([
-    { id: 1, text: "Read the docs", done: false },
-    { id: 2, text: "Build something", done: false },
-  ]);
-  const draft = signal("");
-  let nextId = 3;
-
-  const add = (e: Event) => {
-    e.preventDefault();
-    const text = draft.value.trim();
-    if (!text) return;
-    items.value = [...items.value, { id: nextId++, text, done: false }];
-    draft.value = "";
-  };
 
   return (
     <main>
-      <h1>⚡ {{name}}</h1>
-      <p class="muted">
-        This component ran once. Every value below is a signal bound to exactly one DOM node.
-      </p>
-
-      <section class="card">
-        <h2>Counter</h2>
-        <div class="row">
-          <button onClick={() => count.value--}>−</button>
-          <output>{count}</output>
-          <button onClick={() => count.value++}>+</button>
-        </div>
-        <p class="muted">double = {double}</p>
-      </section>
-
-      <section class="card">
-        <h2>List</h2>
-        <form class="row" onSubmit={add}>
-          <input value={draft} onInput={(e) => (draft.value = e.currentTarget.value)} placeholder="Add an item" />
-          <button type="submit" disabled={!draft.value.trim()}>Add</button>
-        </form>
-        <ul>
-          <For each={items.value} fallback={<li class="muted">Nothing here yet.</li>}>
-            {(item) => (
-              <li classList={{ done: item.done }}>
-                <label>
-                  <input
-                    type="checkbox"
-                    checked={item.done}
-                    onChange={() => (items.value = items.value.map((i) => (i.id === item.id ? { ...i, done: !i.done } : i)))}
-                  />
-                  {item.text}
-                </label>
-                <button class="link" onClick={() => (items.value = items.value.filter((i) => i.id !== item.id))}>
-                  remove
-                </button>
-              </li>
-            )}
-          </For>
-        </ul>
-        <Show when={items.value.some((i) => i.done)}>
-          <p class="muted">{items.value.filter((i) => i.done).length} done</p>
-        </Show>
-      </section>
+      <a href="https://www.npmjs.com/package/create-voltapp" target="_blank" rel="noreferrer">
+        <svg class="logo" viewBox="0 0 24 24" aria-hidden="true">
+          <path d="M13.5 2 4 14h7l-1.5 8L20 10h-7z" />
+        </svg>
+      </a>
+      <h1>{{name}}</h1>
+      <div class="card">
+        <button type="button" onClick={() => count.value++}>
+          count is {count}
+        </button>
+        <p>
+          Edit <code>src/main.tsx</code> and save to test HMR
+        </p>
+      </div>
+      <p class="muted">Components run once. <code>count</code> is a signal bound to exactly one text node.</p>
     </main>
   );
 }

package/templates/minimal/src/styles.css

@@ -1,84 +1,50 @@
 :root {
   color-scheme: light dark;
   font: 16px/1.5 system-ui, sans-serif;
+  --accent: #8b8bff;
   --border: color-mix(in srgb, currentColor 18%, transparent);
 }
 body {
   margin: 0;
 }
 main {
-  max-width: 560px;
-  margin: 3rem auto;
-  padding: 0 1rem;
-  display: grid;
-  gap: 1rem;
+  max-width: 640px;
+  margin: 0 auto;
+  padding: 4rem 1rem;
+  text-align: center;
 }
-h1,
-h2,
-p {
-  margin: 0;
+.logo {
+  width: 5rem;
+  height: 5rem;
+  fill: var(--accent);
+  filter: drop-shadow(0 0 1.5rem color-mix(in srgb, var(--accent) 60%, transparent));
 }
-.muted {
-  opacity: 0.65;
-  font-size: 0.9rem;
+h1 {
+  font-size: 2.5rem;
+  margin: 0.5rem 0 1.5rem;
 }
 .card {
-  border: 1px solid var(--border);
-  border-radius: 10px;
-  padding: 1rem;
   display: grid;
-  gap: 0.75rem;
-}
-.row {
-  display: flex;
-  gap: 0.5rem;
-  align-items: center;
-}
-output {
-  min-width: 3ch;
-  text-align: center;
-  font-size: 1.5rem;
-  font-weight: 600;
-}
-input[type="text"],
-input:not([type]) {
-  flex: 1;
-  padding: 0.5rem;
-  border: 1px solid var(--border);
-  border-radius: 6px;
-  background: transparent;
-  color: inherit;
+  gap: 1rem;
+  justify-items: center;
+  padding: 2rem;
 }
 button {
-  padding: 0.45rem 0.9rem;
+  padding: 0.6rem 1.2rem;
+  font: inherit;
   border: 1px solid var(--border);
-  border-radius: 999px;
+  border-radius: 8px;
   background: transparent;
   color: inherit;
   cursor: pointer;
 }
-button:disabled {
-  opacity: 0.4;
-  cursor: not-allowed;
+button:hover {
+  border-color: var(--accent);
 }
-button.link {
-  border: 0;
-  opacity: 0.6;
-  font-size: 0.85rem;
+code {
+  font-size: 0.9em;
 }
-ul {
-  list-style: none;
-  margin: 0;
-  padding: 0;
-  display: grid;
-  gap: 0.25rem;
-}
-li {
-  display: flex;
-  justify-content: space-between;
-  align-items: center;
-}
-li.done label {
-  text-decoration: line-through;
-  opacity: 0.6;
+.muted {
+  opacity: 0.65;
+  font-size: 0.9rem;
 }

package/templates/todo/README.md

@@ -0,0 +1,28 @@
+# {{name}}
+
+A full-stack Volt demo: server-side rendering, a Vite dev server with HMR, typed routing, server functions and live queries with automatic invalidation.
+
+```sh
+npm install
+npm run dev      # http://localhost:5173
+npm run build    # client + server bundles in dist/
+npm start        # production server
+```
+
+## Layout
+
+```
+server.ts                 HTTP server (dev: Vite middleware; prod: dist/)
+src/todos.server.ts       queries and mutations — never shipped to the browser
+src/App.tsx               routes and components
+src/entry-client.tsx      render() in the browser
+src/entry-server.tsx      renderToString() for SSR
+```
+
+## How data flows
+
+1. `listTodos` is a `query`: while it runs, `todos.read()` records a dependency.
+2. `addTodo` is a `mutation`: `todos.write()` records a change.
+3. The client's `useQuery(listTodos, filter)` refetches whenever a mutation writes `todos`, in every open tab, pushed over `/_volt/live`.
+
+Requires Node 24 or newer (TypeScript runs natively).

package/templates/todo/_gitignore

@@ -0,0 +1,3 @@
+node_modules/
+dist/
+.DS_Store

package/templates/todo/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{{name}}</title>
+    <link rel="stylesheet" href="/src/styles.css" />
+  </head>
+  <body>
+    <div id="app"><!--ssr-outlet--></div>
+    <script type="module" src="/src/entry-client.tsx"></script>
+  </body>
+</html>

package/templates/todo/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "{{name}}",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "node server.ts",
+    "build": "vite build --outDir dist/client && vite build --ssr src/entry-server.tsx --outDir dist/server",
+    "start": "node server.ts --prod",
+    "check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@prouzbek/data": "{{version}}",
+    "@prouzbek/dom": "{{version}}",
+    "@prouzbek/router": "{{version}}",
+    "@prouzbek/serialize": "{{version}}",
+    "@prouzbek/server": "{{version}}",
+    "@prouzbek/signals": "{{version}}"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@prouzbek/vite": "{{version}}",
+    "typescript": "^5.9.0",
+    "vite": "^8.0.0"
+  }
+}

package/templates/todo/server.ts

@@ -0,0 +1,66 @@
+/**
+ * One server for development and production.
+ *   npm run dev    → Vite in middleware mode (HMR) + SSR compiled on the fly
+ *   npm run build  → client + server bundles in dist/
+ *   npm start      → serves dist/ with SSR
+ *
+ * Server functions (`*.server.ts`) and the live channel are plain middleware.
+ */
+import { createServer } from "node:http";
+import { existsSync, readFileSync } from "node:fs";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { dirname, extname, join } from "node:path";
+import { createApp, logger } from "@prouzbek/server";
+import { serverFunctions } from "@prouzbek/server/fn";
+import { live } from "@prouzbek/data/server";
+import { toRequest, sendResponse } from "@prouzbek/server/node";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const isProd = process.argv.includes("--prod") || process.env.NODE_ENV === "production";
+const port = Number(process.env.PORT ?? 5173);
+
+const app = createApp().use(logger()).use(live()).use(serverFunctions());
+
+let vite: import("vite").ViteDevServer | undefined;
+let template: string;
+let renderPage: (url: string, request: Request) => Promise<string>;
+
+if (!isProd) {
+  const { createServer: createVite } = await import("vite");
+  vite = await createVite({ root: here, server: { middlewareMode: true }, appType: "custom" });
+  template = readFileSync(join(here, "index.html"), "utf8");
+} else {
+  template = readFileSync(join(here, "dist/client/index.html"), "utf8");
+  renderPage = (await import(pathToFileURL(join(here, "dist/server/entry-server.js")).href)).render;
+}
+
+app.get("*", async (c) => {
+  const url = c.url.pathname + c.url.search;
+  let html = template;
+  if (vite) {
+    html = await vite.transformIndexHtml(url, template);
+    renderPage = (await vite.ssrLoadModule("/src/entry-server.tsx")).render;
+  }
+  return c.html(html.replace("<!--ssr-outlet-->", await renderPage(url, c.request)));
+});
+
+const types: Record<string, string> = { ".js": "text/javascript", ".css": "text/css", ".svg": "image/svg+xml", ".woff2": "font/woff2" };
+
+createServer((req, res) => {
+  const handle = () =>
+    app
+      .fetch(toRequest(req))
+      .then((r) => sendResponse(r, res))
+      .catch((e) => {
+        console.error(e);
+        if (!res.headersSent) res.writeHead(500);
+        res.end("Internal Server Error");
+      });
+  if (vite) return vite.middlewares(req, res, () => void handle());
+  const asset = join(here, "dist/client", req.url ?? "");
+  if (isProd && req.url?.startsWith("/assets/") && existsSync(asset)) {
+    res.writeHead(200, { "content-type": types[extname(asset)] ?? "application/octet-stream", "cache-control": "public, max-age=31536000, immutable" });
+    return res.end(readFileSync(asset));
+  }
+  void handle();
+}).listen(port, () => console.log(`⚡ {{name}} → http://localhost:${port}`));

package/templates/todo/src/App.tsx

@@ -0,0 +1,101 @@
+import { signal } from "@prouzbek/signals";
+import { For, Show } from "@prouzbek/dom";
+import { route, Link, Outlet, useSearchParams, type RouteDef } from "@prouzbek/router";
+import { useQuery, useMutation } from "@prouzbek/data/client";
+import { listTodos, addTodo, toggleTodo, removeTodo, type Filter, type Todo } from "./todos.server.ts";
+
+function Layout() {
+  return (
+    <>
+      <nav>
+        <Link href="/" activeClass="active">Todos</Link>
+        <Link href="/about" activeClass="active">About</Link>
+      </nav>
+      <Outlet />
+    </>
+  );
+}
+
+function Todos() {
+  const [params, setParams] = useSearchParams();
+  const filter = () => (params.value.get("filter") as Filter | null) ?? "all";
+  const list = useQuery(listTodos, filter);
+  const draft = signal("");
+
+  const add = useMutation(addTodo, {
+    optimistic: (cache, title) =>
+      cache.updateAll(listTodos, (cur) => [...cur, { id: -Date.now(), title, done: false, createdAt: new Date() }]),
+  });
+  const toggle = useMutation(toggleTodo, {
+    optimistic: (cache, id) => cache.updateAll(listTodos, (cur) => cur.map((t) => (t.id === id ? { ...t, done: !t.done } : t))),
+  });
+  const remove = useMutation(removeTodo, {
+    optimistic: (cache, id) => cache.updateAll(listTodos, (cur) => cur.filter((t) => t.id !== id)),
+  });
+
+  return (
+    <section>
+      <h1>⚡ {{name}}</h1>
+      <p class="muted">
+        Server-rendered, live-synced todos. Open this page in two tabs.
+        <Show when={add.queued.value > 0}> · {add.queued.value} queued offline</Show>
+      </p>
+      <p class="filters">
+        {(["all", "open", "done"] as Filter[]).map((f) => (
+          <button type="button" disabled={filter() === f} onClick={() => void setParams({ filter: f === "all" ? null : f })}>
+            {f}
+          </button>
+        ))}
+      </p>
+      <form
+        onSubmit={(e) => {
+          e.preventDefault();
+          const title = draft.value;
+          draft.value = "";
+          void add.run(title).catch(() => {});
+        }}
+      >
+        <input value={draft} onInput={(e) => (draft.value = e.currentTarget.value)} placeholder="What needs doing?" />
+        <button type="submit" disabled={!draft.value.trim()}>Add</button>
+      </form>
+      <Show when={add.error.value}>{(err) => <p class="muted">⚠ {String((err.value as Error).message)}</p>}</Show>
+      <Show when={list.data.value} fallback={<p class="muted">Loading…</p>}>
+        <ul>
+          <For each={list.data.value ?? []} fallback={<li class="muted">Nothing here.</li>}>
+            {(todo: Todo) => (
+              <li classList={{ done: todo.done, pending: todo.id < 0 }}>
+                <label>
+                  <input type="checkbox" checked={todo.done} disabled={todo.id < 0} onChange={() => void toggle.run(todo.id)} />
+                  <span>{todo.title}</span>
+                </label>
+                <button class="link" type="button" disabled={todo.id < 0} onClick={() => void remove.run(todo.id)}>
+                  remove
+                </button>
+              </li>
+            )}
+          </For>
+        </ul>
+      </Show>
+    </section>
+  );
+}
+
+function About() {
+  return (
+    <section>
+      <h1>About</h1>
+      <p>
+        <code>src/todos.server.ts</code> never reaches the browser. The client calls its exports as typed RPC stubs, and
+        every query refetches automatically when a mutation writes the source it read.
+      </p>
+    </section>
+  );
+}
+
+export const routes: RouteDef[] = [
+  route({
+    path: "/",
+    component: Layout,
+    children: [route({ path: "", component: Todos }), route({ path: "about", component: About })],
+  }),
+];

package/templates/todo/src/entry-client.tsx

@@ -0,0 +1,11 @@
+import { render } from "@prouzbek/dom";
+import { createRouter, RouterProvider } from "@prouzbek/router";
+import { createQueryClient, provideQueryClient } from "@prouzbek/data/client";
+import { routes } from "./App.tsx";
+
+const client = createQueryClient({ storage: localStorage });
+const router = createRouter(routes);
+
+const root = document.getElementById("app")!;
+root.innerHTML = "";
+render(() => provideQueryClient(client, () => <RouterProvider router={router} />), root);

package/templates/todo/src/entry-server.tsx

@@ -0,0 +1,14 @@
+import { renderToString } from "@prouzbek/dom";
+import { createRouter, RouterProvider } from "@prouzbek/router";
+import { createQueryClient, provideQueryClient } from "@prouzbek/data/client";
+import { routes } from "./App.tsx";
+
+export async function render(url: string, request: Request): Promise<string> {
+  const client = createQueryClient({ liveUrl: false });
+  const router = createRouter(routes, { url, request });
+  await router.ready;
+  const html = renderToString(() => provideQueryClient(client, () => <RouterProvider router={router} />));
+  client.dispose();
+  router.dispose();
+  return html;
+}

package/templates/todo/src/styles.css

@@ -0,0 +1,80 @@
+:root {
+  color-scheme: light dark;
+  font: 16px/1.5 system-ui, sans-serif;
+  --border: color-mix(in srgb, currentColor 18%, transparent);
+}
+body {
+  max-width: 560px;
+  margin: 2rem auto;
+  padding: 0 1rem;
+}
+nav {
+  display: flex;
+  gap: 1rem;
+  margin-bottom: 1.5rem;
+}
+nav a {
+  color: inherit;
+  opacity: 0.7;
+}
+nav a.active {
+  opacity: 1;
+  font-weight: 600;
+  text-decoration: underline;
+}
+h1 {
+  margin: 0 0 0.25rem;
+}
+.muted {
+  opacity: 0.65;
+  font-size: 0.9rem;
+}
+.filters,
+form {
+  display: flex;
+  gap: 0.5rem;
+  margin: 1rem 0;
+}
+form input {
+  flex: 1;
+  padding: 0.5rem;
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  background: transparent;
+  color: inherit;
+}
+button {
+  padding: 0.4rem 0.9rem;
+  border: 1px solid var(--border);
+  border-radius: 999px;
+  background: transparent;
+  color: inherit;
+  cursor: pointer;
+}
+button:disabled {
+  opacity: 0.4;
+  cursor: not-allowed;
+}
+button.link {
+  border: 0;
+  opacity: 0.6;
+  font-size: 0.85rem;
+}
+ul {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+}
+li {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 0.3rem 0;
+}
+li.done span {
+  text-decoration: line-through;
+  opacity: 0.6;
+}
+li.pending {
+  opacity: 0.5;
+}

package/templates/todo/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "jsx": "preserve",
+    "jsxImportSource": "@prouzbek/dom",
+    "strict": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "skipLibCheck": true,
+    "types": ["node", "vite/client"]
+  },
+  "include": ["src", "server.ts", "vite.config.ts"]
+}

package/templates/todo/vite.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "vite";
+import volt from "@prouzbek/vite";
+
+export default defineConfig({
+  plugins: [volt()],
+  appType: "custom",
+  server: { middlewareMode: true },
+  build: { manifest: true },
+});