create-voltapp 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Volt contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,15 @@
-# Temporary Holding Version
+# create-voltapp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Scaffold a new Volt app: npm create voltapp@latest my-app
+
+Part of **Volt**, a full-stack TypeScript framework with fine-grained signals, a compiler-checked server boundary and live queries with automatic invalidation. Zero runtime dependencies.
+
+```sh
+npm create voltapp@latest my-app
+```
+
+Templates: `minimal` (client app), `fullstack` (SSR, server functions, live queries), `api` (server only).
+
+Documentation and examples: see the Volt repository (`llms.txt` has the whole API on one page).
+
+MIT licensed.

package/bin/create-voltapp.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+/**
+ * create-voltapp — scaffold a Volt app.
+ *
+ *   npm create voltapp@latest my-app
+ *   npm create voltapp@latest my-app -- --template fullstack
+ *   npx create-voltapp my-app --template api
+ *
+ * Zero dependencies. Copies a template, fills in the project name and the
+ * matching @prouzbek/* version, and prints the next steps.
+ */
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve, basename } from "node:path";
+import { createInterface } from "node:readline/promises";
+
+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.",
+  api: "Server only: Web-standard app with validation, sessions and server functions.",
+};
+
+const args = process.argv.slice(2);
+const flag = (name) => {
+  const i = args.indexOf(`--${name}`);
+  return i >= 0 ? args[i + 1] : undefined;
+};
+let dir = args.find((a) => !a.startsWith("--") && args[args.indexOf(a) - 1] !== "--template");
+let template = flag("template");
+
+const bold = (s) => `\u001b[1m${s}\u001b[22m`;
+const dim = (s) => `\u001b[2m${s}\u001b[22m`;
+const accent = (s) => `\u001b[38;5;141m${s}\u001b[39m`;
+
+console.log(`\n${accent("⚡")} ${bold("create-voltapp")} ${dim("v" + pkg.version)}\n`);
+
+const rl = createInterface({ input: process.stdin, output: process.stdout });
+try {
+  if (!dir) {
+    dir = (await rl.question(`${bold("Project name")} ${dim("(my-volt-app)")}: `)).trim() || "my-volt-app";
+  }
+  if (!template) {
+    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();
+    template = names[Number(answer) - 1] ?? (names.includes(answer) ? answer : "fullstack");
+  }
+} finally {
+  rl.close();
+}
+
+if (!TEMPLATES[template]) {
+  console.error(`Unknown template "${template}". Available: ${Object.keys(TEMPLATES).join(", ")}`);
+  process.exit(1);
+}
+
+const target = resolve(process.cwd(), dir);
+const name = basename(target).toLowerCase().replace(/[^a-z0-9-_.]/g, "-");
+if (existsSync(target) && readdirSync(target).length) {
+  console.error(`\n✗ ${target} exists and is not empty.`);
+  process.exit(1);
+}
+mkdirSync(target, { recursive: true });
+
+const source = join(here, "..", "templates", template);
+cpSync(source, target, { recursive: true });
+
+// npm drops .gitignore from published packages, so templates ship it as _gitignore
+const gi = join(target, "_gitignore");
+if (existsSync(gi)) renameSync(gi, join(target, ".gitignore"));
+
+// fill placeholders
+const walk = (d) => readdirSync(d).flatMap((f) => (statSync(join(d, f)).isDirectory() ? walk(join(d, f)) : [join(d, f)]));
+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.frameworkVersion ?? pkg.version);
+  if (next !== text) writeFileSync(file, next);
+}
+
+const pm = (process.env.npm_config_user_agent ?? "").split("/")[0] || "npm";
+const run = (s) => (pm === "npm" ? `npm run ${s}` : `${pm} ${s}`);
+
+console.log(`\n${accent("✓")} Created ${bold(name)} from the ${bold(template)} template.\n`);
+console.log(`  cd ${dir}`);
+console.log(`  ${pm} install`);
+console.log(`  ${run("dev")}\n`);
+console.log(dim("Docs: the whole API is in node_modules/@prouzbek/*/README.md and the repository's llms.txt.\n"));

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "create-voltapp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "frameworkVersion": "0.1.0",
+  "description": "Scaffold a new Volt app: npm create voltapp@latest my-app",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "create-voltapp": "bin/create-voltapp.js"
+  },
+  "files": [
+    "bin",
+    "templates"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/prouzbek/volt",
+  "keywords": [
+    "volt",
+    "signals",
+    "reactive",
+    "framework",
+    "typescript",
+    "create",
+    "scaffold"
+  ]
+}

package/templates/api/README.md

@@ -0,0 +1,13 @@
+# {{name}}
+
+A Volt API server with validation, sessions and server functions. No build step: Node 24 runs TypeScript directly.
+
+```sh
+npm install
+npm run dev                     # http://localhost:3000, restarts on change
+curl -X POST localhost:3000/signup -H 'content-type: application/json' -d '{"email":"a@b.co","password":"secret123"}'
+curl -c jar -X POST localhost:3000/login -H 'content-type: application/json' -d '{"email":"a@b.co","password":"secret123"}'
+curl -b jar localhost:3000/notes
+```
+
+Set `SESSION_SECRET` in production. Deploy anywhere that speaks `fetch`: Node, Bun, Deno, Cloudflare Workers.

package/templates/api/_gitignore

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+.env
+.DS_Store

package/templates/api/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "{{name}}",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "node --watch server.ts",
+    "start": "node server.ts",
+    "check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@prouzbek/kit": "{{version}}",
+    "@prouzbek/serialize": "{{version}}",
+    "@prouzbek/server": "{{version}}"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0"
+  }
+}

package/templates/api/server.ts

@@ -0,0 +1,61 @@
+/**
+ * A Volt API server: Web-standard app, validation, sessions, server functions.
+ * Runs on Node (below), Bun (`Bun.serve({ fetch: app.fetch })`), Deno
+ * (`Deno.serve(app.fetch)`) and Cloudflare Workers (`export default app`).
+ */
+import { createApp, HttpError, logger, cors } from "@prouzbek/server";
+import { serverFunctions, serverFn } from "@prouzbek/server/fn";
+import { serve } from "@prouzbek/server/node";
+import { v, body, sessions, requireAuth, hashPassword, verifyPassword, loadEnv } from "@prouzbek/kit";
+
+const env = loadEnv({
+  PORT: v.number().coerce().default(3000),
+  SESSION_SECRET: v.string().min(16).default("change-me-change-me-change-me"),
+});
+
+// ── an in-memory "database" ──
+type User = { id: string; email: string; hash: string };
+const users = new Map<string, User>();
+const notes: { id: number; userId: string; text: string }[] = [];
+
+type State = { session: import("@prouzbek/kit").Session<{ userId: string }>; body?: unknown };
+
+export const app = createApp<State>()
+  .use(logger())
+  .use(cors())
+  .use(sessions<{ userId: string }>({ secret: env.SESSION_SECRET, cookieOptions: { secure: false } }))
+  .use(serverFunctions())
+
+  .get("/", () => ({ name: "{{name}}", docs: "/notes requires a session: POST /signup then POST /login" }))
+
+  .post("/signup", body(v.object({ email: v.string().email(), password: v.string().min(8) })), async (c) => {
+    const { email, password } = c.state.body as { email: string; password: string };
+    if ([...users.values()].some((u) => u.email === email)) throw new HttpError(409, "Email already registered");
+    const user: User = { id: crypto.randomUUID(), email, hash: await hashPassword(password) };
+    users.set(user.id, user);
+    c.status = 201;
+    return { id: user.id };
+  })
+
+  .post("/login", body(v.object({ email: v.string().email(), password: v.string() })), async (c) => {
+    const { email, password } = c.state.body as { email: string; password: string };
+    const user = [...users.values()].find((u) => u.email === email);
+    if (!user || !(await verifyPassword(password, user.hash))) throw new HttpError(401, "Invalid credentials");
+    c.state.session.set({ userId: user.id });
+    c.state.session.regenerate();
+    return { ok: true };
+  })
+
+  .get("/notes", requireAuth(), (c) => notes.filter((n) => n.userId === c.state.session.data.userId))
+
+  .post("/notes", requireAuth(), body(v.object({ text: v.string().min(1).max(500) })), (c) => {
+    const note = { id: notes.length + 1, userId: c.state.session.data.userId!, text: (c.state.body as { text: string }).text };
+    notes.push(note);
+    c.status = 201;
+    return note;
+  });
+
+// A server function, callable from a Volt client as `await ping("hi")`.
+export const ping = serverFn(async (message: string) => ({ message, at: new Date() }));
+
+serve(app, { port: env.PORT, onListen: ({ port }) => console.log(`⚡ {{name}} → http://localhost:${port}`) });

package/templates/api/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "strict": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "erasableSyntaxOnly": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["*.ts", "src"]
+}

package/templates/fullstack/README.md

@@ -0,0 +1,28 @@
+# {{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.
+
+```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/fullstack/_gitignore

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

package/templates/fullstack/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/fullstack/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/fullstack/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/fullstack/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/fullstack/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/fullstack/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/fullstack/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/fullstack/src/todos.server.ts

@@ -0,0 +1,43 @@
+/**
+ * Server-only module. The browser build replaces this file with RPC stubs, so
+ * nothing here (including the in-memory "database") can reach the client.
+ */
+import { source, query, mutation } from "@prouzbek/data/server";
+import { HttpError } from "@prouzbek/server";
+
+export type Todo = { id: number; title: string; done: boolean; createdAt: Date };
+export type Filter = "all" | "open" | "done";
+
+const todos = source("todos");
+const db: Todo[] = [{ id: 1, title: "Explore the code", done: false, createdAt: new Date() }];
+let nextId = 2;
+
+export const listTodos = query(async (filter: Filter) => {
+  todos.read();
+  return db.filter((t) => (filter === "all" ? true : filter === "open" ? !t.done : t.done));
+});
+
+export const addTodo = mutation(async (title: string) => {
+  title = title.trim();
+  if (!title) throw new HttpError(422, "Title is required");
+  const todo: Todo = { id: nextId++, title, done: false, createdAt: new Date() };
+  db.push(todo);
+  todos.write();
+  return todo;
+});
+
+export const toggleTodo = mutation(async (id: number) => {
+  const t = db.find((x) => x.id === id);
+  if (!t) throw new HttpError(404, "No such todo");
+  t.done = !t.done;
+  todos.write(id);
+  todos.write();
+  return t;
+});
+
+export const removeTodo = mutation(async (id: number) => {
+  const i = db.findIndex((x) => x.id === id);
+  if (i >= 0) db.splice(i, 1);
+  todos.write();
+  return id;
+});

package/templates/fullstack/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/fullstack/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 },
+});

package/templates/minimal/README.md

@@ -0,0 +1,13 @@
+# {{name}}
+
+A Volt client app.
+
+```sh
+npm install
+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.
+- `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`.

package/templates/minimal/_gitignore

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

package/templates/minimal/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{{name}}</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/minimal/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "{{name}}",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@prouzbek/dom": "{{version}}",
+    "@prouzbek/signals": "{{version}}"
+  },
+  "devDependencies": {
+    "@prouzbek/vite": "{{version}}",
+    "typescript": "^5.9.0",
+    "vite": "^8.0.0"
+  }
+}

package/templates/minimal/src/main.tsx

@@ -0,0 +1,76 @@
+import { signal, computed } from "@prouzbek/signals";
+import { render, For, Show } 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>
+    </main>
+  );
+}
+
+render(() => <App />, document.getElementById("app")!);

package/templates/minimal/src/styles.css

@@ -0,0 +1,84 @@
+:root {
+  color-scheme: light dark;
+  font: 16px/1.5 system-ui, sans-serif;
+  --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;
+}
+h1,
+h2,
+p {
+  margin: 0;
+}
+.muted {
+  opacity: 0.65;
+  font-size: 0.9rem;
+}
+.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;
+}
+button {
+  padding: 0.45rem 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;
+  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;
+}

package/templates/minimal/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": ["vite/client"]
+  },
+  "include": ["src"]
+}

package/templates/minimal/vite.config.ts

@@ -0,0 +1,6 @@
+import { defineConfig } from "vite";
+import volt from "@prouzbek/vite";
+
+export default defineConfig({
+  plugins: [volt()],
+});