create-volt 0.3.2 → 0.8.0

package/addons/realtime/files/public/chat-client.js

@@ -0,0 +1,30 @@
+// chat-client.js — thin browser wrapper around the Socket.io chat events.
+// Pair it with Volt signals in your app.js. Requires the socket.io client
+// (load /socket.io/socket.io.js before your module).
+//
+//   import { createChat } from "/chat-client.js";
+//   const chat = createChat({
+//     onHistory:  ({ room, messages }) => ...,
+//     onMessage:  (msg) => ...,
+//     onPresence: ({ room, users }) => ...,
+//     onTyping:   ({ name }) => ...,
+//   });
+//   chat.join("general");
+//   chat.send("general", "hello");
+//   chat.typing("general");
+
+export function createChat({ onHistory, onMessage, onPresence, onTyping } = {}) {
+  if (!window.io) throw new Error("Socket.io client not loaded — add <script src=\"/socket.io/socket.io.js\"></script>");
+  const socket = window.io();
+  if (onHistory) socket.on("chat:history", onHistory);
+  if (onMessage) socket.on("chat:message", onMessage);
+  if (onPresence) socket.on("chat:presence", onPresence);
+  if (onTyping) socket.on("chat:typing", onTyping);
+
+  return {
+    socket,
+    join: (room) => socket.emit("chat:join", { room }),
+    send: (room, body) => socket.emit("chat:message", { room, body }),
+    typing: (room) => socket.emit("chat:typing", { room }),
+  };
+}

package/addons/realtime/meta.json

@@ -0,0 +1,8 @@
+{
+  "description": "Socket.io live chat: rooms, presence (who's online), typing indicators. Persists messages via db; shows emails when auth is present.",
+  "dependsOn": ["db"],
+  "sentinel": "lib/realtime.js",
+  "install": ["socket.io"],
+  "optional": {},
+  "wiring": "import http from \"node:http\";\nimport { Server as SocketServer } from \"socket.io\";\nimport { createStore } from \"./lib/store.js\";\nimport { attachRealtime } from \"./lib/realtime.js\";\n\nconst server = http.createServer(app);   // wrap the Express app\nconst io = new SocketServer(server);\nattachRealtime(io, { store: await createStore() });\nserver.listen(PORT);                     // listen on `server`, not `app`\n\nIn the page: load /socket.io/socket.io.js, then in your module:\n  import { createChat } from \"/chat-client.js\";\n  const chat = createChat({ onMessage, onHistory, onPresence, onTyping });\n  chat.join(\"general\"); chat.send(\"general\", \"hi\");"
+}

package/config/config-app.js

@@ -0,0 +1,168 @@
+// config-app.js — the disposable add-on configurator, built with Volt itself.
+import { signal, computed, html, mount } from "/volt.js";
+
+const datePort = () => {
+  const d = new Date();
+  return `${String(d.getFullYear()).slice(-2)}${d.getMonth() + 1}${String(d.getDate()).padStart(2, "0")}`;
+};
+
+const addons = await (await fetch("/addons.json")).json();
+const current = await (await fetch("/current.json")).json(); // existing .env, so Apply doesn't clobber it
+const byName = (n) => addons.find((a) => a.name === n);
+
+const state = signal({
+  addons: Object.fromEntries(addons.map((a) => [a.name, a.installed])),
+  dbDriver: current.DB_DRIVER || "memory",
+  mongoUri: current.MONGODB_URI || "",
+  mongoDb: current.MONGODB_DATABASE || "",
+  dbUrl: current.DATABASE_URL || "",
+  smtpUrl: current.SMTP_URL || "",
+  mailFrom: current.MAIL_FROM || "",
+  port: current.PORT || datePort(),
+});
+const set = (patch) => state({ ...state(), ...patch });
+const toggle = (n) => state({ ...state(), addons: { ...state().addons, [n]: !state().addons[n] } });
+const status = signal("");
+
+// --- generators ---
+function genEnv(s) {
+  const out = [];
+  if (s.port) out.push(`PORT=${s.port}`);
+  if (s.addons.db) {
+    out.push(`DB_DRIVER=${s.dbDriver}`);
+    if (s.dbDriver === "mongodb") {
+      out.push(`MONGODB_URI=${s.mongoUri}`);
+      if (s.mongoDb) out.push(`MONGODB_DATABASE=${s.mongoDb}`);
+    } else if (s.dbDriver === "mysql" || s.dbDriver === "postgres") {
+      out.push(`DATABASE_URL=${s.dbUrl}`);
+    }
+  }
+  if (s.addons.mailer) {
+    if (s.smtpUrl) out.push(`SMTP_URL=${s.smtpUrl}`);
+    else out.push(`# SMTP_URL=        # unset → emails print to the console`);
+    if (s.mailFrom) out.push(`MAIL_FROM=${s.mailFrom}`);
+  }
+  return out.join("\n") + "\n";
+}
+function genInstall(s) {
+  const deps = new Set();
+  for (const a of addons) if (s.addons[a.name]) (a.install || []).forEach((d) => deps.add(d));
+  if (s.addons.db) {
+    if (s.dbDriver === "mongodb") deps.add("mongodb");
+    if (s.dbDriver === "mysql") deps.add("mysql2");
+    if (s.dbDriver === "postgres") deps.add("pg");
+  }
+  if (s.addons.mailer && s.smtpUrl) deps.add("nodemailer");
+  return deps.size ? `npm install ${[...deps].join(" ")}` : "# no extra packages needed";
+}
+function genWiring(s) {
+  const parts = [];
+  for (const name of ["db", "mailer", "auth", "realtime"]) {
+    if (s.addons[name]) parts.push(`// ── ${name} ──\n${byName(name).wiring}`);
+  }
+  return parts.join("\n\n") || "// select add-ons above";
+}
+function warnings(s) {
+  const w = [];
+  if (s.addons.auth && (!s.addons.db || !s.addons.mailer)) w.push("auth needs db + mailer");
+  if (s.addons.realtime && !s.addons.db) w.push("realtime needs db (for message persistence)");
+  return w;
+}
+
+const env = computed(() => genEnv(state()));
+
+const KEY = new URLSearchParams(location.search).get("key") || "";
+const copy = (text) => navigator.clipboard.writeText(text).then(() => (status("Copied."), setTimeout(() => status(""), 1500)));
+const setAll = (v) => state({ ...state(), addons: Object.fromEntries(addons.map((a) => [a.name, v])) });
+async function apply() {
+  const selected = Object.keys(state().addons).filter((n) => state().addons[n]);
+  status("Applying…");
+  const r = await fetch("/apply", { method: "POST", headers: { "Content-Type": "application/json", "x-config-key": KEY }, body: JSON.stringify({ addons: selected, env: env() }) });
+  const d = await r.json();
+  status(d.ok ? `Applied ${selected.join(", ") || "(none)"} — copied ${d.copied.length} file(s) + wrote .env. Next: ${genInstall(state())} · npm run dev` : `Error: ${d.error}`);
+  setTimeout(() => status(""), 9000);
+}
+
+// --- views ---
+const addonToggles = () =>
+  html`<div class="card-x p-4 mb-3">
+    <div class="d-flex justify-content-between align-items-center mb-3">
+      <h2 class="h6 mb-0">Add-ons</h2>
+      <div>
+        <button class="btn btn-sm btn-outline-secondary" onclick=${() => setAll(true)}>All</button>
+        <button class="btn btn-sm btn-outline-secondary ms-1" onclick=${() => setAll(false)}>None</button>
+      </div>
+    </div>
+    ${addons.map(
+      (a) => html`<div class="form-check mb-2">
+        <input class="form-check-input" type="checkbox" id=${"x-" + a.name}
+               checked=${() => state().addons[a.name]} onchange=${() => toggle(a.name)} />
+        <label class="form-check-label" for=${"x-" + a.name}>
+          <span class="accent">${a.name}</span>${a.installed ? " · installed" : ""}
+          <div class="small text-muted">${a.description}</div>
+        </label>
+      </div>`,
+    )}
+  </div>`;
+
+const field = (label, key, placeholder = "") =>
+  html`<div class="mb-2">
+    <label class="form-label small mb-1">${label}</label>
+    <input class="form-control" placeholder=${placeholder}
+           value=${() => state()[key]} oninput=${(e) => set({ [key]: e.target.value })} />
+  </div>`;
+
+const settings = () =>
+  html`<div class="card-x p-4 mb-3">
+    <h2 class="h6 mb-3">Settings</h2>
+    ${field("PORT", "port", "26628")}
+    ${() =>
+      state().addons.db
+        ? html`<div class="mb-2">
+              <label class="form-label small mb-1">DB_DRIVER</label>
+              <select class="form-select" value=${() => state().dbDriver} onchange=${(e) => set({ dbDriver: e.target.value })}>
+                <option value="memory">memory (no setup)</option>
+                <option value="mongodb">mongodb</option>
+                <option value="mysql">mysql</option>
+                <option value="postgres">postgres</option>
+              </select>
+            </div>
+            ${() =>
+              state().dbDriver === "mongodb"
+                ? html`${field("MONGODB_URI", "mongoUri", "mongodb://user:pass@host:27017/db")}${field("MONGODB_DATABASE", "mongoDb", "db")}`
+                : state().dbDriver === "mysql" || state().dbDriver === "postgres"
+                  ? field("DATABASE_URL", "dbUrl", state().dbDriver + "://user:pass@host/db")
+                  : null}`
+        : null}
+    ${() => (state().addons.mailer ? html`${field("SMTP_URL (optional)", "smtpUrl", "smtp://user:pass@smtp.host:587")}${field("MAIL_FROM", "mailFrom", "App <no-reply@you.com>")}` : null)}
+  </div>`;
+
+const warnRow = () =>
+  html`${() => {
+    const w = warnings(state());
+    return w.length ? html`<div class="alert alert-warning py-2 small">⚠ ${w.join(" · ")}</div>` : null;
+  }}`;
+
+const output = (title, getText, withWrite = false) =>
+  html`<div class="card-x p-4 mb-3">
+    <div class="d-flex justify-content-between align-items-center mb-2">
+      <h2 class="h6 mb-0">${title}</h2>
+      <div>
+        <button class="btn btn-sm btn-outline-secondary" onclick=${() => copy(getText())}>Copy</button>
+        ${withWrite ? html`<button class="btn btn-sm btn-primary ms-2" onclick=${apply}>Apply</button>` : null}
+      </div>
+    </div>
+    <pre class="mb-0">${getText}</pre>
+  </div>`;
+
+mount(
+  "#app",
+  addonToggles(),
+  settings(),
+  warnRow(),
+  output(".env", env, true),
+  html`<p class="small text-muted mb-3">The app auto-loads <code>.env</code> on start — just run <code>npm run dev</code> (no flags; same on Windows).</p>`,
+  output("Install", computed(() => genInstall(state()))),
+  output("server.js wiring", computed(() => genWiring(state()))),
+  () => (status() ? html`<p class="small accent">${status}</p>` : null),
+);

package/config/index.html

@@ -0,0 +1,29 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>create-volt · configure add-ons</title>
+  <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css" rel="stylesheet" />
+  <style>
+    body { background: #0f1115; color: #e7e9ee; }
+    .accent { color: #ffd24a; }
+    .card-x { background: #161a22; border: 1px solid #232a36; border-radius: 14px; }
+    .form-control, .form-select { background: #0f1115; color: #e7e9ee; border-color: #232a36; }
+    .form-control:focus, .form-select:focus { background: #0f1115; color: #e7e9ee; border-color: #ffd24a; box-shadow: none; }
+    pre { background: #0b0d11; border: 1px solid #232a36; border-radius: 10px; padding: 12px; color: #cfe3ff; white-space: pre-wrap; }
+    a { color: #ffd24a; }
+    code { color: #ffd24a; }
+  </style>
+</head>
+<body>
+  <main class="container py-5" style="max-width: 760px;">
+    <header class="mb-4">
+      <h1 class="h3"><span class="accent">⚡ create-volt</span> · configure add-ons</h1>
+      <p class="text-muted mb-0">Pick add-ons, fill in settings, write your <code>.env</code>. This page is disposable — close the terminal when you're done.</p>
+    </header>
+    <div id="app"></div>
+  </main>
+  <script type="module" src="/config-app.js"></script>
+</body>
+</html>

package/index.js

@@ -10,6 +10,9 @@
 
 import fs from "node:fs";
 import path from "node:path";
+import http from "node:http";
+import os from "node:os";
+import crypto from "node:crypto";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
@@ -34,11 +37,16 @@ ${bold("⚡ create-volt")} — scaffold a new Volt app
 ${bold("Usage")}
   npm create volt@latest <project-directory> [options]
   npx create-volt <project-directory> [options]
+  npx create-volt@latest update              # refresh public/volt.js in an existing app
+  npx create-volt@latest config              # disposable page: add db/auth/realtime/mailer + write .env
 
 ${bold("Options")}
-  --port <number>  Dev port for the app (default: derived from today's date)
+  --template <name>  Starter template: default | guestbook  (default: default)
+  --port <number>    Dev port for the app (default: derived from today's date)
   --skip-install   Don't run the package manager install step
   --no-git         Don't initialize a git repository
+  --start          After scaffolding, run the dev server (opens the setup page)
+  --no-open        Don't auto-open the browser on start
   --dry-run        Show what would be created without writing anything
   --force          Scaffold into an existing non-empty directory
   -h, --help       Show this help
@@ -54,10 +62,16 @@ const argv = process.argv.slice(2);
 const flags = new Set();
 const positionals = [];
 let portArg = null;
+let templateArg = null;
+let hostArg = null;
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
   if (a === "--port") portArg = argv[++i];
   else if (a.startsWith("--port=")) portArg = a.slice("--port=".length);
+  else if (a === "--template") templateArg = argv[++i];
+  else if (a.startsWith("--template=")) templateArg = a.slice("--template=".length);
+  else if (a === "--host") hostArg = argv[++i];
+  else if (a.startsWith("--host=")) hostArg = a.slice("--host=".length);
   else if (a.startsWith("-")) flags.add(a);
   else positionals.push(a);
 }
@@ -76,6 +90,196 @@ const force = flags.has("--force");
 const dryRun = flags.has("--dry-run");
 const noGit = flags.has("--no-git");
 
+// The `add` command was replaced by `config` — catch old muscle memory.
+if (positionals[0] === "add") {
+  die(`${cyan("add")} was replaced by ${cyan("create-volt config")} — run that to add integrations.`);
+}
+
+// --- `update` subcommand: refresh public/volt.js in the current app to the
+// version bundled with this create-volt (so `npx create-volt@latest update`
+// pulls the latest library). Only touches the library file — never the user's
+// app.js, server.js, or port. ---
+if (positionals[0] === "update") {
+  const target = path.join(process.cwd(), "public", "volt.js");
+  if (!fs.existsSync(target)) {
+    die(`No ${cyan("public/volt.js")} here — run ${cyan("create-volt update")} from inside a Volt app.`);
+  }
+  const latest = fs.readFileSync(path.join(__dirname, "templates", "default", "public", "volt.js"), "utf8");
+  const current = fs.readFileSync(target, "utf8");
+  if (current === latest) {
+    console.log(`\n${green("✔")} ${bold("public/volt.js")} is already current (create-volt ${pkg.version}).\n`);
+    process.exit(0);
+  }
+  if (dryRun) {
+    console.log(`\n${yellow("!")} An update is available for ${bold("public/volt.js")} (create-volt ${pkg.version}).`);
+    console.log(`  Re-run without ${cyan("--dry-run")} to apply.\n`);
+    process.exit(0);
+  }
+  fs.writeFileSync(target, latest);
+  console.log(`\n${green("✔")} Updated ${bold("public/volt.js")} to the version in create-volt ${pkg.version}.`);
+  console.log(`  Review the change with ${cyan("git diff public/volt.js")}.\n`);
+  process.exit(0);
+}
+
+// --- `config` subcommand: a disposable local page to configure add-ons and
+// write a .env. Dependency-free (node:http); the page is built with Volt. ---
+if (positionals[0] === "config") {
+  const cwd = process.cwd();
+  const addonsDir = path.join(__dirname, "addons");
+  const addonList = fs
+    .readdirSync(addonsDir, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => {
+      const m = JSON.parse(fs.readFileSync(path.join(addonsDir, e.name, "meta.json"), "utf8"));
+      return {
+        name: e.name,
+        description: m.description,
+        install: m.install || [],
+        dependsOn: m.dependsOn || [],
+        wiring: m.wiring,
+        installed: fs.existsSync(path.join(cwd, m.sentinel)),
+      };
+    });
+  const assets = {
+    "/config-app.js": ["text/javascript; charset=utf-8", fs.readFileSync(path.join(__dirname, "config", "config-app.js"))],
+    "/volt.js": ["text/javascript; charset=utf-8", fs.readFileSync(path.join(__dirname, "templates", "default", "public", "volt.js"))],
+  };
+  const indexHtml = fs.readFileSync(path.join(__dirname, "config", "index.html"));
+  // localhost by default — shell/SSH access is the auth. --host exposes it on the
+  // network, and only then do we mint a random key to gate it.
+  const host = hostArg || "127.0.0.1";
+  const exposed = host !== "127.0.0.1" && host !== "localhost";
+  const key = exposed ? crypto.randomBytes(12).toString("hex") : null;
+
+  const server = http.createServer((req, res) => {
+    const u = new URL(req.url, "http://localhost");
+    const p = u.pathname;
+    if (req.method === "GET" && p === "/") {
+      if (key && u.searchParams.get("key") !== key) {
+        res.statusCode = 403;
+        return res.end("Forbidden — open the ?key=… link printed in the terminal.");
+      }
+      res.setHeader("Content-Type", "text/html; charset=utf-8");
+      return res.end(indexHtml);
+    }
+    if (req.method === "GET" && assets[p]) {
+      res.setHeader("Content-Type", assets[p][0]);
+      return res.end(assets[p][1]);
+    }
+    if (req.method === "GET" && p === "/addons.json") {
+      res.setHeader("Content-Type", "application/json");
+      return res.end(JSON.stringify(addonList));
+    }
+    if (req.method === "GET" && p === "/current.json") {
+      const current = {};
+      const envPath = path.join(cwd, ".env");
+      if (fs.existsSync(envPath)) {
+        for (const line of fs.readFileSync(envPath, "utf8").split("\n")) {
+          const m = line.match(/^\s*([A-Za-z0-9_]+)\s*=\s*(.*?)\s*$/);
+          if (m) current[m[1]] = m[2];
+        }
+      }
+      res.setHeader("Content-Type", "application/json");
+      return res.end(JSON.stringify(current));
+    }
+    if (req.method === "POST" && p === "/apply") {
+      if (key && req.headers["x-config-key"] !== key) {
+        res.statusCode = 403;
+        return res.end(JSON.stringify({ ok: false, error: "bad or missing key" }));
+      }
+      let body = "";
+      req.on("data", (c) => (body += c));
+      req.on("end", () => {
+        try {
+          const { addons = [], env } = JSON.parse(body);
+          const valid = new Set(addonList.map((a) => a.name));
+          const depsOf = Object.fromEntries(addonList.map((a) => [a.name, a.dependsOn]));
+          // expand selection to include required dependencies (deps before dependents)
+          const want = [];
+          const seen = new Set();
+          const visit = (n) => {
+            if (!valid.has(n) || seen.has(n)) return;
+            seen.add(n);
+            for (const d of depsOf[n] || []) visit(d);
+            want.push(n);
+          };
+          for (const n of addons) visit(n);
+
+          const copied = [];
+          const skipped = [];
+          for (const n of want) {
+            const filesDir = path.join(addonsDir, n, "files");
+            for (const f of listTemplateFiles(filesDir)) {
+              const dest = path.join(cwd, f);
+              if (fs.existsSync(dest)) {
+                skipped.push(f);
+                continue;
+              }
+              fs.mkdirSync(path.dirname(dest), { recursive: true });
+              fs.copyFileSync(path.join(filesDir, f), dest);
+              copied.push(f);
+            }
+          }
+          if (typeof env === "string") {
+            // preserve any custom keys already in .env that this form doesn't manage
+            const envPath = path.join(cwd, ".env");
+            let finalEnv = env;
+            if (fs.existsSync(envPath)) {
+              const managed = new Set([...env.matchAll(/^\s*([A-Za-z0-9_]+)\s*=/gm)].map((m) => m[1]));
+              const extra = fs
+                .readFileSync(envPath, "utf8")
+                .split("\n")
+                .filter((line) => {
+                  const m = line.match(/^\s*([A-Za-z0-9_]+)\s*=/);
+                  return m && !managed.has(m[1]);
+                });
+              if (extra.length) finalEnv = env.replace(/\n*$/, "\n") + extra.join("\n") + "\n";
+            }
+            fs.writeFileSync(envPath, finalEnv);
+          }
+          console.log(`${green("✔")} applied [${want.join(", ")}] — ${copied.length} file(s) copied, .env written`);
+          res.setHeader("Content-Type", "application/json");
+          res.end(JSON.stringify({ ok: true, copied, skipped, applied: want }));
+        } catch (e) {
+          res.statusCode = 400;
+          res.end(JSON.stringify({ ok: false, error: e.message }));
+        }
+      });
+      return;
+    }
+    res.statusCode = 404;
+    res.end("not found");
+  });
+
+  const wanted = portArg ? Number(portArg) : 0;
+  server.listen(Number.isInteger(wanted) && wanted > 0 ? wanted : 0, host, () => {
+    const port = server.address().port;
+    const q = key ? `/?key=${key}` : "/";
+    console.log(`\n${bold("⚡ create-volt config")} — add-ons for ${dim(cwd)}\n`);
+    if (exposed) {
+      const lan = [];
+      for (const iface of Object.values(os.networkInterfaces())) {
+        for (const a of iface || []) if (a.family === "IPv4" && !a.internal) lan.push(a.address);
+      }
+      console.log("  Open (key-gated, reachable on your network):");
+      for (const ip of lan) console.log("    " + cyan(`http://${ip}:${port}${q}`));
+      console.log("    " + cyan(`http://localhost:${port}${q}`) + dim("   (this box)"));
+    } else {
+      const url = `http://localhost:${port}${q}`;
+      console.log("  Open: " + cyan(url));
+      const ssh = process.env.SSH_CONNECTION; // "clientIP clientPort serverIP serverPort"
+      const user = process.env.USER || process.env.USERNAME || "you";
+      const sshHost = ssh ? ssh.split(" ")[2] : os.hostname();
+      console.log(`  ${dim(ssh ? "Remote box — the server is up here; from your LOCAL machine run:" : "Remote box? from your local machine run:")}`);
+      console.log("    " + dim(`ssh -N -L 127.0.0.1:${port}:localhost:${port} ${user}@${sshHost}`));
+      console.log(`  ${dim(`…then open ${url} on your machine — shell access is the auth.`)}`);
+      console.log(`  ${dim("(LAN access instead: --host 0.0.0.0 — adds a key)")}`);
+    }
+    console.log(`\n  ${dim("Applies add-ons + writes .env here · Ctrl-C when done (disposable).")}\n`);
+  });
+  await new Promise(() => {}); // keep the server up; never fall through to scaffolding
+}
+
 // Resolve the dev port: --port wins, else derive it from today's date as
 // two-digit-year + month (no leading zero) + two-digit-day (house convention),
 // so apps scaffolded on different days don't collide on the same port.
@@ -112,7 +316,19 @@ if (!/^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/.test(path.basena
 
 const targetDir = path.resolve(process.cwd(), projectName);
 const appName = path.basename(targetDir);
-const templateDir = path.join(__dirname, "template");
+
+// Resolve the starter template (default | guestbook | …).
+const templatesDir = path.join(__dirname, "templates");
+const templateName = templateArg || "default";
+const templateDir = path.join(templatesDir, templateName);
+if (!fs.existsSync(templateDir) || !fs.statSync(templateDir).isDirectory()) {
+  const available = fs
+    .readdirSync(templatesDir, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .join(", ");
+  die(`Unknown template "${templateName}". Available: ${available}.`);
+}
 
 // List every file in the template, relative to its root (for dry-run preview).
 function listTemplateFiles(dir, base = dir) {
@@ -135,7 +351,7 @@ if (fs.existsSync(targetDir)) {
 
 // --- dry run: print the plan and exit without writing anything ---
 if (dryRun) {
-  console.log(`\n${bold("⚡ Dry run")} — would create a Volt app in ${cyan(targetDir)}\n`);
+  console.log(`\n${bold("⚡ Dry run")} — would create a ${cyan(templateName)} Volt app in ${cyan(targetDir)}\n`);
   console.log("Would write:");
   for (const f of listTemplateFiles(templateDir).sort()) {
     // the shipped "gitignore" is renamed to ".gitignore" on scaffold
@@ -171,23 +387,19 @@ fs.writeFileSync(appPkgPath, JSON.stringify(appPkg, null, 2) + "\n");
 
 // --- stamp the chosen dev port into server.js + README ---
 const serverPath = path.join(targetDir, "server.js");
-fs.writeFileSync(
-  serverPath,
-  fs.readFileSync(serverPath, "utf8").replace(/(Number\(process\.env\.PORT\)\s*\|\|\s*)\d+/, `$1${port}`),
-);
+let serverSrc = fs.readFileSync(serverPath, "utf8");
+serverSrc = serverSrc.replace(/(const DEFAULT_PORT\s*=\s*)\d+/, `$1${port}`); // default template
+serverSrc = serverSrc.replace(/(Number\(process\.env\.PORT\)\s*\|\|\s*)\d+/, `$1${port}`); // other templates
+fs.writeFileSync(serverPath, serverSrc);
 const appReadme = path.join(targetDir, "README.md");
 if (fs.existsSync(appReadme)) {
   fs.writeFileSync(appReadme, fs.readFileSync(appReadme, "utf8").replace(/localhost:\d+/g, `localhost:${port}`));
 }
 
-const created = [
-  "public/volt.js   — the Volt library (no build step)",
-  "public/app.js    — your app (Counter + Todos demo)",
-  "views/index.html — the HTML shell",
-  "server.js        — dev server with hot reload",
-];
-console.log(green("✔") + " Files created:");
-for (const line of created) console.log("  " + dim(line));
+console.log(green("✔") + ` Created a ${cyan(templateName)} app — files:`);
+for (const f of listTemplateFiles(templateDir).sort()) {
+  console.log("  " + dim(f === "gitignore" ? ".gitignore" : f));
+}
 console.log("");
 
 // --- detect the package manager that invoked us (npm / pnpm / yarn / bun) ---
@@ -248,4 +460,18 @@ console.log(`\n${green("✔")} ${bold("Done!")} Next steps:\n`);
 console.log(`  ${cyan("cd")} ${projectName}`);
 if (!installed) console.log(`  ${cyan(installCmd)}`);
 console.log(`  ${cyan(runCmd)}`);
-console.log(`\nThen open ${cyan("http://localhost:" + port)} and edit ${bold("public/app.js")}.\n`);
+console.log(`\nFirst run opens a quick ${bold("setup")} page at ${cyan("http://localhost:" + port)}, then your app starts.\n`);
+
+if (flags.has("--start")) {
+  if (!installed) {
+    console.log(dim(`(--start needs dependencies — run ${installCmd}, then ${runCmd}.)\n`));
+  } else {
+    console.log(`${bold("Starting…")}\n`);
+    spawnSync(pm, ["run", "dev"], {
+      cwd: targetDir,
+      stdio: "inherit",
+      shell: process.platform === "win32",
+      env: flags.has("--no-open") ? { ...process.env, VOLT_NO_OPEN: "1" } : process.env,
+    });
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-volt",
-  "version": "0.3.2",
+  "version": "0.8.0",
   "description": "Scaffold a new Volt app — no-build, signals-based UI with Socket.io hot reload.",
   "type": "module",
   "bin": {
@@ -8,7 +8,10 @@
   },
   "files": [
     "index.js",
-    "template"
+    "templates",
+    "addons",
+    "config",
+    "CHANGELOG.md"
   ],
   "engines": {
     "node": ">=16.7.0"

package/{template → templates/default}/README.md

@@ -4,13 +4,21 @@ A tiny, **no-build**, signals-based UI app with **Socket.io hot reload**.
 Not React: no JSX, no virtual DOM, no re-render-the-world. State lives in
 *signals*; only the exact text/attribute that changed updates.
 
+📖 **[How to build a Volt app →](https://github.com/MIR-2025/volt#readme)**
+
 ## Run
 
 ```bash
 npm install        # if you scaffolded with --skip-install
-npm run dev        # → http://localhost:26628   (PORT env to override)
+npm run dev        # → http://localhost:26628
 ```
 
+The **first run opens a quick setup page** in your browser (configure settings,
+click Apply, and the app starts — the setup page then disappears). On a headless
+or remote box it prints the link instead. Reopen settings anytime with
+`npm run dev -- --edit` (`-e`). `.env` is auto-loaded, so no `--env-file` flag
+is needed — it works the same on Windows.
+
 Edit anything in `public/` or `views/` and save — the dev server pushes a
 reload over Socket.io and the page refreshes itself.
 
@@ -30,6 +38,17 @@ date and takes `--port <number>` to avoid collisions on the same day:
 npm create volt@latest api-app -- --port 26630
 ```
 
+## Updating Volt
+
+`public/volt.js` is a vendored file, not an npm dependency. Pull the latest
+library version with:
+
+```bash
+npx create-volt@latest update
+```
+
+This rewrites only `public/volt.js` — your app code and port stay as-is.
+
 ## Project layout
 
 ```