create-volt 0.39.1 → 0.41.0

package/CHANGELOG.md

@@ -4,6 +4,26 @@ All notable changes to `create-volt` are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/), and this project adheres to
 [Semantic Versioning](https://semver.org/).
 
+## [0.41.0] - 2026-06-30
+
+### Added
+- **PM2 support.** Scaffolds ship `ecosystem.config.cjs` + scripts: `npm run pm2`
+  (start under pm2 — fetched via npx if not installed, or uses your global pm2),
+  `pm2:restart` (clean reload, no port clash), `pm2:logs`, `pm2:stop`.
+- **`npm run dev` on an already-running app reloads it instead of crashing.** A
+  second start detects the in-use port, pings the running instance's new
+  `/__volt/reload` route to refresh browsers, prints a note, and exits 0 — no
+  more `EADDRINUSE` stack trace.
+
+## [0.40.0] - 2026-06-30
+
+### Added
+- **Themed front page.** `pages/index.md` now takes over `/` (rendered in your
+  theme), so a content site's home matches the rest of the site instead of
+  showing the demo `views/index.html`. With no `pages/index.md`, `/` stays the
+  app's index.html. (Answers: "I chose a theme but the home page was unchanged" —
+  the theme styles pages/posts; the home needs to *be* a page.)
+
 ## [0.39.1] - 2026-06-30
 
 ### Fixed
@@ -528,6 +548,8 @@ All notable changes to `create-volt` are documented here. The format follows
   watching and full-page hot reload. Supports `--skip-install` and `--force`,
   and auto-detects npm / pnpm / yarn / bun for the install step.
 
+[0.41.0]: https://github.com/MIR-2025/volt/releases/tag/v0.41.0
+[0.40.0]: https://github.com/MIR-2025/volt/releases/tag/v0.40.0
 [0.39.1]: https://github.com/MIR-2025/volt/releases/tag/v0.39.1
 [0.39.0]: https://github.com/MIR-2025/volt/releases/tag/v0.39.0
 [0.38.0]: https://github.com/MIR-2025/volt/releases/tag/v0.38.0

package/addons/pages/files/lib/pages.js

@@ -176,20 +176,29 @@ export async function pagesRouter({ dir }) {
   const { marked } = await import("marked");
   ensure(dir);
   const getTheme = themeResolver(dir);
+  // render one markdown file into the theme. `format: html` pages (e.g. from the
+  // WYSIWYG editor) are served verbatim; everything else is rendered with marked.
+  const renderFile = async (file, fallbackTitle, res) => {
+    const { meta, body } = parseFrontMatter(fs.readFileSync(file, "utf8"));
+    const content = meta.format === "html" ? body : marked.parse(body);
+    const m = { ...meta, title: meta.title || fallbackTitle };
+    const { layout } = await getTheme();
+    res.type("html").send(injectHot(layout({ title: m.title, head: metaHead(m), content, meta: m })));
+  };
   const r = express.Router();
   r.get("/_theme.css", async (_req, res) => res.type("css").send((await getTheme()).css));
+  // themed home: pages/index.md takes over "/" (the site's front page) when present
+  r.get("/", async (_req, res, next) => {
+    const file = path.join(dir, "index.md");
+    if (!fs.existsSync(file)) return next();
+    await renderFile(file, "Home", res);
+  });
   r.get("/:slug", async (req, res, next) => {
     const slug = req.params.slug;
     if (!isSafeSlug(slug)) return next(); // safe slug only — no traversal
     const file = path.join(dir, slug + ".md");
     if (!fs.existsSync(file)) return next();
-    const { meta, body } = parseFrontMatter(fs.readFileSync(file, "utf8"));
-    // `format: html` pages (e.g. from the WYSIWYG editor) are served verbatim to
-    // preserve complex layouts; everything else is markdown rendered with marked.
-    const content = meta.format === "html" ? body : marked.parse(body);
-    const m = { ...meta, title: meta.title || slug };
-    const { layout } = await getTheme();
-    res.type("html").send(injectHot(layout({ title: m.title, head: metaHead(m), content, meta: m })));
+    await renderFile(file, slug, res);
   });
   return r;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-volt",
-  "version": "0.39.1",
+  "version": "0.41.0",
   "description": "Scaffold a new Volt app — no-build, signals-based UI with Socket.io hot reload.",
   "type": "module",
   "bin": {

package/templates/blog/ecosystem.config.cjs

@@ -0,0 +1,5 @@
+// PM2 process config. Start under pm2 with `npm run pm2` (pm2 is fetched via npx
+// if you don't have it installed); reload cleanly with `npm run pm2:restart` (no
+// port clash), tail logs with `npm run pm2:logs`, remove with `npm run pm2:stop`.
+const { name } = require("./package.json");
+module.exports = { apps: [{ name, script: "server.js" }] };

package/templates/blog/package.json

@@ -7,7 +7,11 @@
   "main": "server.js",
   "scripts": {
     "start": "node server.js",
-    "dev": "node server.js"
+    "dev": "node server.js",
+    "pm2": "npx --yes pm2 start ecosystem.config.cjs",
+    "pm2:restart": "npx --yes pm2 restart ecosystem.config.cjs",
+    "pm2:stop": "npx --yes pm2 delete ecosystem.config.cjs",
+    "pm2:logs": "npx --yes pm2 logs"
   },
   "dependencies": {
     "express": "^4.22.2",

package/templates/blog/server.js

@@ -1,9 +1,9 @@
-// server.js — dev server with a built-in first-run setup wizard.
+// server.js — dev server with a built-in first-run setup wizard.
 //
 // First run (no .env) or `node server.js --edit` (-e) opens a disposable, local
 // config page: tick add-ons, fill settings, Apply. Apply writes .env (a
 // VOLT_ADDONS list + settings) and adds any needed packages to package.json,
-// runs npm install, then starts the app — which wires whatever .env enables.
+// runs npm install, then starts the app — which wires whatever .env enables.
 // Add-on code is bundled under .volt/addons; nothing is copied into your code.
 //
 // No build step, no env-file flag: .env is auto-loaded below.
@@ -24,7 +24,7 @@ const THEMES_DIR = path.join(__dirname, ".volt", "themes"); // bundled themes th
 const DEFAULT_PORT = 26628; // create-volt stamps this with the project's date-port
 const CONFIG_DEFAULT_PORT = 5050; // the --edit/--studio config UI's default port (its own, so it never clashes with a running app)
 
-// `--port <n>` (or --port=<n>) overrides the listen port for this run — lets
+// `--port <n>` (or --port=<n>) overrides the listen port for this run — lets
 // --edit/--studio dodge a port the running app already holds, and runs the app
 // itself on a one-off port. Explicit flag wins over PORT in .env.
 function cliPort() {
@@ -104,7 +104,7 @@ const imp = (rel) => import(pathToFileURL(path.join(__dirname, rel)).href);
 const addonMod = (n) => imp(path.join(".volt", "addons", n, "files", "lib", LIB_FILE[n]));
 
 // Built-in add-ons are wired explicitly below; everything else in VOLT_ADDONS is
-// a third-party add-on — a local .volt/addons/<name>/index.js or an installed
+// a third-party add-on — a local .volt/addons/<name>/index.js or an installed
 // npm package "volt-addon-<name>" exporting register(ctx). See /docs/plugins.
 const BUILTINS = new Set(Object.keys(LIB_FILE));
 async function loadAddon(name) {
@@ -128,7 +128,7 @@ function openBrowser(url) {
   const args = plat === "win32" ? ["/c", "start", "", url] : [url];
   try {
     const child = spawn(cmd, args, { stdio: "ignore", detached: true });
-    child.on("error", () => {}); // launcher missing — emits async, don't crash
+    child.on("error", () => {}); // launcher missing — emits async, don't crash
     child.unref();
     return true;
   } catch {
@@ -163,7 +163,11 @@ async function startApp() {
     if (fs.existsSync(pub)) app.use(express.static(pub));
   }
 
-  app.get("/", (_req, res) => res.sendFile(path.join(__dirname, "views", "index.html")));
+  app.get("/", (_req, res, next) => {
+    // a themed home page (pages/index.md) takes over "/" — else the app's index.html
+    if (enabled.has("pages") && fs.existsSync(path.join(__dirname, "pages", "index.md"))) return next();
+    res.sendFile(path.join(__dirname, "views", "index.html"));
+  });
 
   // media uploads (POST /api/media, auth-gated; local files served at /media)
   if (enabled.has("media") && store) {
@@ -171,8 +175,8 @@ async function startApp() {
     app.use(await (await addonMod("media")).mediaRouter({ requireAuth, dir: path.join(__dirname, "media") }));
   }
 
-  // markdown pages (/<slug> ← pages/<slug>.md) — mounted last, so app routes win
-  // blog posts (/blog, /blog/<slug>, /category, /tag, /feed.xml) — before pages so /blog wins; renders in the same theme.
+  // markdown pages (/<slug> ← pages/<slug>.md) — mounted last, so app routes win
+  // blog posts (/blog, /blog/<slug>, /category, /tag, /feed.xml) — before pages so /blog wins; renders in the same theme.
   if (enabled.has("posts")) app.use(await (await addonMod("posts")).postsRouter({ dir: path.join(__dirname, "posts"), themeDir: path.join(__dirname, "pages") }));
   if (enabled.has("pages")) app.use(await (await addonMod("pages")).pagesRouter({ dir: path.join(__dirname, "pages") }));
 
@@ -180,7 +184,14 @@ async function startApp() {
   const io = new SocketServer(server);
   if (enabled.has("realtime") && store) (await addonMod("realtime")).attachRealtime(io, { store });
 
-  // third-party add-ons — register(ctx). When auth is on, requireAuth/sessionFromReq
+  // Reload connected browsers on demand — used when a second `npm run dev` finds
+  // the app already running (see the EADDRINUSE handler below) instead of crashing.
+  app.get("/__volt/reload", (_req, res) => {
+    io.emit("volt:reload", { file: "__manual__" });
+    res.json({ ok: true });
+  });
+
+  // third-party add-ons — register(ctx). When auth is on, requireAuth/sessionFromReq
   // are provided so add-ons can gate routes by login.
   let requireAuth = null;
   let sessionFromReq = null;
@@ -196,7 +207,7 @@ async function startApp() {
     if (typeof register === "function") {
       await register({ app, express, io, store, mailer, env: process.env, requireAuth, sessionFromReq, log: (...a) => console.log(`[${name}]`, ...a) });
     } else {
-      console.warn(`[volt] add-on "${name}" not found or missing a register() export — skipped`);
+      console.warn(`[volt] add-on "${name}" not found or missing a register() export — skipped`);
     }
   }
 
@@ -204,7 +215,7 @@ async function startApp() {
   const onChange = (file) => {
     clearTimeout(timer);
     timer = setTimeout(() => {
-      console.log(`[volt] change: ${file ?? "?"} → reload`);
+      console.log(`[volt] change: ${file ?? "?"} → reload`);
       io.emit("volt:reload", { file });
     }, 80);
   };
@@ -233,7 +244,21 @@ async function startApp() {
   }
 
   const on = [...enabled];
-  server.listen(PORT, () => console.log(`⚡ Volt → http://localhost:${PORT}${on.length ? "  (add-ons: " + on.join(", ") + ")" : ""}`));
+  // If the port's taken, the app is likely already running — reload it (tell the
+  // running instance to refresh browsers) and exit, instead of an EADDRINUSE crash.
+  server.on("error", async (e) => {
+    if (e.code === "EADDRINUSE") {
+      try {
+        await fetch(`http://localhost:${PORT}/__volt/reload`);
+      } catch {
+        /* old instance without the reload route, or not ours */
+      }
+      console.log(`\n[volt] already running at http://localhost:${PORT} — reloaded it. (Stop that process, or use pm2, to restart.)`);
+      process.exit(0);
+    }
+    throw e;
+  });
+  server.listen(PORT, () => console.log(`⚡ Volt → http://localhost:${PORT}${on.length ? "  (add-ons: " + on.join(", ") + ")" : ""}`));
 }
 
 // Packages an .env's selections need, beyond what package.json already has.
@@ -257,7 +282,7 @@ function neededPackages(env) {
 function ensureDriverInstalled(driver) {
   const pkg = { mongodb: "mongodb", mongo: "mongodb", mysql: "mysql2", postgres: "pg", postgresql: "pg", pg: "pg" }[String(driver || "").toLowerCase()];
   if (!pkg || fs.existsSync(path.join(__dirname, "node_modules", pkg))) return;
-  console.log(`[volt] installing ${pkg} for the connection test…`);
+  console.log(`[volt] installing ${pkg} for the connection test…`);
   spawnSync("npm", ["install", `${pkg}@${PKG_VERSIONS[pkg] || "latest"}`], { cwd: __dirname, stdio: "inherit", shell: process.platform === "win32" });
 }
 
@@ -380,15 +405,15 @@ function startSetup() {
               server.closeIdleConnections?.();
             };
             if (added.length) {
-              console.log(`[volt] installing ${added.join(", ")}…`);
+              console.log(`[volt] installing ${added.join(", ")}…`);
               const npm = spawn("npm", ["install"], { cwd: __dirname, stdio: "inherit", shell: process.platform === "win32" });
               npm.on("error", () => handoff());
               npm.on("close", () => {
-                console.log("[volt] saved .env — starting the app…");
+                console.log("[volt] saved .env — starting the app…");
                 handoff();
               });
             } else {
-              console.log("[volt] saved .env — starting the app…");
+              console.log("[volt] saved .env — starting the app…");
               handoff();
             }
           });
@@ -406,18 +431,18 @@ function startSetup() {
   server.on("error", (e) => { if (e.code === "EADDRINUSE") { console.error(`\n[volt] Config UI port ${PORT} is in use (is the app already running?). Set CONFIG_PORT in .env or pass --port <n>.\n`); process.exit(1); } throw e; });
   server.listen(PORT, "127.0.0.1", () => {
     const url = `http://localhost:${PORT}`;
-    console.log(`\n⚡ Volt setup → ${url}`);
+    console.log(`\n⚡ Volt setup → ${url}`);
     console.log("  Configure your app; it starts automatically on Apply. (reopen later: npm run dev -- --edit)");
     const ssh = process.env.SSH_CONNECTION;
     if (ssh) {
       const host = ssh.split(" ")[2];
       const user = process.env.USER || process.env.USERNAME || "you";
-      console.log("  Remote box — the server is up here; bridge it from your LOCAL machine:");
+      console.log("  Remote box — the server is up here; bridge it from your LOCAL machine:");
       console.log(`    ssh -N -L 127.0.0.1:${PORT}:localhost:${PORT} ${user}@${host}`);
-      console.log(`  …then open ${url} on your machine (the tunnel points it here).`);
+      console.log(`  …then open ${url} on your machine (the tunnel points it here).`);
     }
     console.log("");
-    if (openBrowser(url)) console.log("  (opening your browser…)\n");
+    if (openBrowser(url)) console.log("  (opening your browser…)\n");
   });
 }
 
@@ -425,8 +450,8 @@ function readEnvFileLines() {
   return fs.existsSync(ENV_PATH) ? fs.readFileSync(ENV_PATH, "utf8").split("\n") : [];
 }
 
-// --- Studio: an ephemeral, localhost-only data browser (à la Prisma Studio).
-// Not a route in the running app — it only exists while you run `--studio`, on
+// --- Studio: an ephemeral, localhost-only data browser (à la Prisma Studio).
+// Not a route in the running app — it only exists while you run `--studio`, on
 // loopback, and disappears on Ctrl-C. Shell/SSH access is the auth. ---
 const HIDDEN_COLLECTIONS = new Set(["auth_tokens", "auth_sessions", "__voltcheck"]);
 async function startStudio() {
@@ -439,7 +464,7 @@ async function startStudio() {
   try {
     store = await (await addonMod("db")).createStore();
   } catch (e) {
-    console.error("Studio: couldn't connect the store — " + e.message);
+    console.error("Studio: couldn't connect the store — " + e.message);
     process.exit(1);
   }
   const PORT = configPort();
@@ -497,15 +522,15 @@ async function startStudio() {
   server.on("error", (e) => { if (e.code === "EADDRINUSE") { console.error(`\n[volt] Config UI port ${PORT} is in use (is the app already running?). Set CONFIG_PORT in .env or pass --port <n>.\n`); process.exit(1); } throw e; });
   server.listen(PORT, "127.0.0.1", () => {
     const url = `http://localhost:${PORT}`;
-    console.log(`\n⚡ Volt Studio → ${url}   (${store.name})`);
-    console.log("  Browse your data. localhost-only, disposable — Ctrl-C when done.");
+    console.log(`\n⚡ Volt Studio → ${url}   (${store.name})`);
+    console.log("  Browse your data. localhost-only, disposable — Ctrl-C when done.");
     const ssh = process.env.SSH_CONNECTION;
     if (ssh) {
       const host = ssh.split(" ")[2];
       const user = process.env.USER || process.env.USERNAME || "you";
-      console.log("  Remote box — from your LOCAL machine:");
+      console.log("  Remote box — from your LOCAL machine:");
       console.log(`    ssh -N -L 127.0.0.1:${PORT}:localhost:${PORT} ${user}@${host}`);
-      console.log(`  …then open ${url}.`);
+      console.log(`  …then open ${url}.`);
     }
     console.log("");
     openBrowser(url);

package/templates/default/ecosystem.config.cjs

@@ -0,0 +1,5 @@
+// PM2 process config. Start under pm2 with `npm run pm2` (pm2 is fetched via npx
+// if you don't have it installed); reload cleanly with `npm run pm2:restart` (no
+// port clash), tail logs with `npm run pm2:logs`, remove with `npm run pm2:stop`.
+const { name } = require("./package.json");
+module.exports = { apps: [{ name, script: "server.js" }] };

package/templates/default/package.json

@@ -7,7 +7,11 @@
   "main": "server.js",
   "scripts": {
     "start": "node server.js",
-    "dev": "node server.js"
+    "dev": "node server.js",
+    "pm2": "npx --yes pm2 start ecosystem.config.cjs",
+    "pm2:restart": "npx --yes pm2 restart ecosystem.config.cjs",
+    "pm2:stop": "npx --yes pm2 delete ecosystem.config.cjs",
+    "pm2:logs": "npx --yes pm2 logs"
   },
   "dependencies": {
     "express": "^4.22.2",

package/templates/default/server.js

@@ -1,9 +1,9 @@
-// server.js — dev server with a built-in first-run setup wizard.
+// server.js — dev server with a built-in first-run setup wizard.
 //
 // First run (no .env) or `node server.js --edit` (-e) opens a disposable, local
 // config page: tick add-ons, fill settings, Apply. Apply writes .env (a
 // VOLT_ADDONS list + settings) and adds any needed packages to package.json,
-// runs npm install, then starts the app — which wires whatever .env enables.
+// runs npm install, then starts the app — which wires whatever .env enables.
 // Add-on code is bundled under .volt/addons; nothing is copied into your code.
 //
 // No build step, no env-file flag: .env is auto-loaded below.
@@ -24,7 +24,7 @@ const THEMES_DIR = path.join(__dirname, ".volt", "themes"); // bundled themes th
 const DEFAULT_PORT = 26628; // create-volt stamps this with the project's date-port
 const CONFIG_DEFAULT_PORT = 5050; // the --edit/--studio config UI's default port (its own, so it never clashes with a running app)
 
-// `--port <n>` (or --port=<n>) overrides the listen port for this run — lets
+// `--port <n>` (or --port=<n>) overrides the listen port for this run — lets
 // --edit/--studio dodge a port the running app already holds, and runs the app
 // itself on a one-off port. Explicit flag wins over PORT in .env.
 function cliPort() {
@@ -104,7 +104,7 @@ const imp = (rel) => import(pathToFileURL(path.join(__dirname, rel)).href);
 const addonMod = (n) => imp(path.join(".volt", "addons", n, "files", "lib", LIB_FILE[n]));
 
 // Built-in add-ons are wired explicitly below; everything else in VOLT_ADDONS is
-// a third-party add-on — a local .volt/addons/<name>/index.js or an installed
+// a third-party add-on — a local .volt/addons/<name>/index.js or an installed
 // npm package "volt-addon-<name>" exporting register(ctx). See /docs/plugins.
 const BUILTINS = new Set(Object.keys(LIB_FILE));
 async function loadAddon(name) {
@@ -128,7 +128,7 @@ function openBrowser(url) {
   const args = plat === "win32" ? ["/c", "start", "", url] : [url];
   try {
     const child = spawn(cmd, args, { stdio: "ignore", detached: true });
-    child.on("error", () => {}); // launcher missing — emits async, don't crash
+    child.on("error", () => {}); // launcher missing — emits async, don't crash
     child.unref();
     return true;
   } catch {
@@ -163,7 +163,11 @@ async function startApp() {
     if (fs.existsSync(pub)) app.use(express.static(pub));
   }
 
-  app.get("/", (_req, res) => res.sendFile(path.join(__dirname, "views", "index.html")));
+  app.get("/", (_req, res, next) => {
+    // a themed home page (pages/index.md) takes over "/" — else the app's index.html
+    if (enabled.has("pages") && fs.existsSync(path.join(__dirname, "pages", "index.md"))) return next();
+    res.sendFile(path.join(__dirname, "views", "index.html"));
+  });
 
   // media uploads (POST /api/media, auth-gated; local files served at /media)
   if (enabled.has("media") && store) {
@@ -171,8 +175,8 @@ async function startApp() {
     app.use(await (await addonMod("media")).mediaRouter({ requireAuth, dir: path.join(__dirname, "media") }));
   }
 
-  // markdown pages (/<slug> ← pages/<slug>.md) — mounted last, so app routes win
-  // blog posts (/blog, /blog/<slug>, /category, /tag, /feed.xml) — before pages so /blog wins; renders in the same theme.
+  // markdown pages (/<slug> ← pages/<slug>.md) — mounted last, so app routes win
+  // blog posts (/blog, /blog/<slug>, /category, /tag, /feed.xml) — before pages so /blog wins; renders in the same theme.
   if (enabled.has("posts")) app.use(await (await addonMod("posts")).postsRouter({ dir: path.join(__dirname, "posts"), themeDir: path.join(__dirname, "pages") }));
   if (enabled.has("pages")) app.use(await (await addonMod("pages")).pagesRouter({ dir: path.join(__dirname, "pages") }));
 
@@ -180,7 +184,14 @@ async function startApp() {
   const io = new SocketServer(server);
   if (enabled.has("realtime") && store) (await addonMod("realtime")).attachRealtime(io, { store });
 
-  // third-party add-ons — register(ctx). When auth is on, requireAuth/sessionFromReq
+  // Reload connected browsers on demand — used when a second `npm run dev` finds
+  // the app already running (see the EADDRINUSE handler below) instead of crashing.
+  app.get("/__volt/reload", (_req, res) => {
+    io.emit("volt:reload", { file: "__manual__" });
+    res.json({ ok: true });
+  });
+
+  // third-party add-ons — register(ctx). When auth is on, requireAuth/sessionFromReq
   // are provided so add-ons can gate routes by login.
   let requireAuth = null;
   let sessionFromReq = null;
@@ -196,7 +207,7 @@ async function startApp() {
     if (typeof register === "function") {
       await register({ app, express, io, store, mailer, env: process.env, requireAuth, sessionFromReq, log: (...a) => console.log(`[${name}]`, ...a) });
     } else {
-      console.warn(`[volt] add-on "${name}" not found or missing a register() export — skipped`);
+      console.warn(`[volt] add-on "${name}" not found or missing a register() export — skipped`);
     }
   }
 
@@ -204,7 +215,7 @@ async function startApp() {
   const onChange = (file) => {
     clearTimeout(timer);
     timer = setTimeout(() => {
-      console.log(`[volt] change: ${file ?? "?"} → reload`);
+      console.log(`[volt] change: ${file ?? "?"} → reload`);
       io.emit("volt:reload", { file });
     }, 80);
   };
@@ -233,7 +244,21 @@ async function startApp() {
   }
 
   const on = [...enabled];
-  server.listen(PORT, () => console.log(`⚡ Volt → http://localhost:${PORT}${on.length ? "  (add-ons: " + on.join(", ") + ")" : ""}`));
+  // If the port's taken, the app is likely already running — reload it (tell the
+  // running instance to refresh browsers) and exit, instead of an EADDRINUSE crash.
+  server.on("error", async (e) => {
+    if (e.code === "EADDRINUSE") {
+      try {
+        await fetch(`http://localhost:${PORT}/__volt/reload`);
+      } catch {
+        /* old instance without the reload route, or not ours */
+      }
+      console.log(`\n[volt] already running at http://localhost:${PORT} — reloaded it. (Stop that process, or use pm2, to restart.)`);
+      process.exit(0);
+    }
+    throw e;
+  });
+  server.listen(PORT, () => console.log(`⚡ Volt → http://localhost:${PORT}${on.length ? "  (add-ons: " + on.join(", ") + ")" : ""}`));
 }
 
 // Packages an .env's selections need, beyond what package.json already has.
@@ -257,7 +282,7 @@ function neededPackages(env) {
 function ensureDriverInstalled(driver) {
   const pkg = { mongodb: "mongodb", mongo: "mongodb", mysql: "mysql2", postgres: "pg", postgresql: "pg", pg: "pg" }[String(driver || "").toLowerCase()];
   if (!pkg || fs.existsSync(path.join(__dirname, "node_modules", pkg))) return;
-  console.log(`[volt] installing ${pkg} for the connection test…`);
+  console.log(`[volt] installing ${pkg} for the connection test…`);
   spawnSync("npm", ["install", `${pkg}@${PKG_VERSIONS[pkg] || "latest"}`], { cwd: __dirname, stdio: "inherit", shell: process.platform === "win32" });
 }
 
@@ -380,15 +405,15 @@ function startSetup() {
               server.closeIdleConnections?.();
             };
             if (added.length) {
-              console.log(`[volt] installing ${added.join(", ")}…`);
+              console.log(`[volt] installing ${added.join(", ")}…`);
               const npm = spawn("npm", ["install"], { cwd: __dirname, stdio: "inherit", shell: process.platform === "win32" });
               npm.on("error", () => handoff());
               npm.on("close", () => {
-                console.log("[volt] saved .env — starting the app…");
+                console.log("[volt] saved .env — starting the app…");
                 handoff();
               });
             } else {
-              console.log("[volt] saved .env — starting the app…");
+              console.log("[volt] saved .env — starting the app…");
               handoff();
             }
           });
@@ -406,18 +431,18 @@ function startSetup() {
   server.on("error", (e) => { if (e.code === "EADDRINUSE") { console.error(`\n[volt] Config UI port ${PORT} is in use (is the app already running?). Set CONFIG_PORT in .env or pass --port <n>.\n`); process.exit(1); } throw e; });
   server.listen(PORT, "127.0.0.1", () => {
     const url = `http://localhost:${PORT}`;
-    console.log(`\n⚡ Volt setup → ${url}`);
+    console.log(`\n⚡ Volt setup → ${url}`);
     console.log("  Configure your app; it starts automatically on Apply. (reopen later: npm run dev -- --edit)");
     const ssh = process.env.SSH_CONNECTION;
     if (ssh) {
       const host = ssh.split(" ")[2];
       const user = process.env.USER || process.env.USERNAME || "you";
-      console.log("  Remote box — the server is up here; bridge it from your LOCAL machine:");
+      console.log("  Remote box — the server is up here; bridge it from your LOCAL machine:");
       console.log(`    ssh -N -L 127.0.0.1:${PORT}:localhost:${PORT} ${user}@${host}`);
-      console.log(`  …then open ${url} on your machine (the tunnel points it here).`);
+      console.log(`  …then open ${url} on your machine (the tunnel points it here).`);
     }
     console.log("");
-    if (openBrowser(url)) console.log("  (opening your browser…)\n");
+    if (openBrowser(url)) console.log("  (opening your browser…)\n");
   });
 }
 
@@ -425,8 +450,8 @@ function readEnvFileLines() {
   return fs.existsSync(ENV_PATH) ? fs.readFileSync(ENV_PATH, "utf8").split("\n") : [];
 }
 
-// --- Studio: an ephemeral, localhost-only data browser (à la Prisma Studio).
-// Not a route in the running app — it only exists while you run `--studio`, on
+// --- Studio: an ephemeral, localhost-only data browser (à la Prisma Studio).
+// Not a route in the running app — it only exists while you run `--studio`, on
 // loopback, and disappears on Ctrl-C. Shell/SSH access is the auth. ---
 const HIDDEN_COLLECTIONS = new Set(["auth_tokens", "auth_sessions", "__voltcheck"]);
 async function startStudio() {
@@ -439,7 +464,7 @@ async function startStudio() {
   try {
     store = await (await addonMod("db")).createStore();
   } catch (e) {
-    console.error("Studio: couldn't connect the store — " + e.message);
+    console.error("Studio: couldn't connect the store — " + e.message);
     process.exit(1);
   }
   const PORT = configPort();
@@ -497,15 +522,15 @@ async function startStudio() {
   server.on("error", (e) => { if (e.code === "EADDRINUSE") { console.error(`\n[volt] Config UI port ${PORT} is in use (is the app already running?). Set CONFIG_PORT in .env or pass --port <n>.\n`); process.exit(1); } throw e; });
   server.listen(PORT, "127.0.0.1", () => {
     const url = `http://localhost:${PORT}`;
-    console.log(`\n⚡ Volt Studio → ${url}   (${store.name})`);
-    console.log("  Browse your data. localhost-only, disposable — Ctrl-C when done.");
+    console.log(`\n⚡ Volt Studio → ${url}   (${store.name})`);
+    console.log("  Browse your data. localhost-only, disposable — Ctrl-C when done.");
     const ssh = process.env.SSH_CONNECTION;
     if (ssh) {
       const host = ssh.split(" ")[2];
       const user = process.env.USER || process.env.USERNAME || "you";
-      console.log("  Remote box — from your LOCAL machine:");
+      console.log("  Remote box — from your LOCAL machine:");
       console.log(`    ssh -N -L 127.0.0.1:${PORT}:localhost:${PORT} ${user}@${host}`);
-      console.log(`  …then open ${url}.`);
+      console.log(`  …then open ${url}.`);
     }
     console.log("");
     openBrowser(url);

package/templates/docs/ecosystem.config.cjs

@@ -0,0 +1,5 @@
+// PM2 process config. Start under pm2 with `npm run pm2` (pm2 is fetched via npx
+// if you don't have it installed); reload cleanly with `npm run pm2:restart` (no
+// port clash), tail logs with `npm run pm2:logs`, remove with `npm run pm2:stop`.
+const { name } = require("./package.json");
+module.exports = { apps: [{ name, script: "server.js" }] };

package/templates/docs/package.json

@@ -7,7 +7,11 @@
   "main": "server.js",
   "scripts": {
     "start": "node server.js",
-    "dev": "node server.js"
+    "dev": "node server.js",
+    "pm2": "npx --yes pm2 start ecosystem.config.cjs",
+    "pm2:restart": "npx --yes pm2 restart ecosystem.config.cjs",
+    "pm2:stop": "npx --yes pm2 delete ecosystem.config.cjs",
+    "pm2:logs": "npx --yes pm2 logs"
   },
   "dependencies": {
     "express": "^4.22.2",

package/templates/docs/server.js

@@ -1,9 +1,9 @@
-// server.js — dev server with a built-in first-run setup wizard.
+// server.js — dev server with a built-in first-run setup wizard.
 //
 // First run (no .env) or `node server.js --edit` (-e) opens a disposable, local
 // config page: tick add-ons, fill settings, Apply. Apply writes .env (a
 // VOLT_ADDONS list + settings) and adds any needed packages to package.json,
-// runs npm install, then starts the app — which wires whatever .env enables.
+// runs npm install, then starts the app — which wires whatever .env enables.
 // Add-on code is bundled under .volt/addons; nothing is copied into your code.
 //
 // No build step, no env-file flag: .env is auto-loaded below.
@@ -24,7 +24,7 @@ const THEMES_DIR = path.join(__dirname, ".volt", "themes"); // bundled themes th
 const DEFAULT_PORT = 26628; // create-volt stamps this with the project's date-port
 const CONFIG_DEFAULT_PORT = 5050; // the --edit/--studio config UI's default port (its own, so it never clashes with a running app)
 
-// `--port <n>` (or --port=<n>) overrides the listen port for this run — lets
+// `--port <n>` (or --port=<n>) overrides the listen port for this run — lets
 // --edit/--studio dodge a port the running app already holds, and runs the app
 // itself on a one-off port. Explicit flag wins over PORT in .env.
 function cliPort() {
@@ -104,7 +104,7 @@ const imp = (rel) => import(pathToFileURL(path.join(__dirname, rel)).href);
 const addonMod = (n) => imp(path.join(".volt", "addons", n, "files", "lib", LIB_FILE[n]));
 
 // Built-in add-ons are wired explicitly below; everything else in VOLT_ADDONS is
-// a third-party add-on — a local .volt/addons/<name>/index.js or an installed
+// a third-party add-on — a local .volt/addons/<name>/index.js or an installed
 // npm package "volt-addon-<name>" exporting register(ctx). See /docs/plugins.
 const BUILTINS = new Set(Object.keys(LIB_FILE));
 async function loadAddon(name) {
@@ -128,7 +128,7 @@ function openBrowser(url) {
   const args = plat === "win32" ? ["/c", "start", "", url] : [url];
   try {
     const child = spawn(cmd, args, { stdio: "ignore", detached: true });
-    child.on("error", () => {}); // launcher missing — emits async, don't crash
+    child.on("error", () => {}); // launcher missing — emits async, don't crash
     child.unref();
     return true;
   } catch {
@@ -163,7 +163,11 @@ async function startApp() {
     if (fs.existsSync(pub)) app.use(express.static(pub));
   }
 
-  app.get("/", (_req, res) => res.sendFile(path.join(__dirname, "views", "index.html")));
+  app.get("/", (_req, res, next) => {
+    // a themed home page (pages/index.md) takes over "/" — else the app's index.html
+    if (enabled.has("pages") && fs.existsSync(path.join(__dirname, "pages", "index.md"))) return next();
+    res.sendFile(path.join(__dirname, "views", "index.html"));
+  });
 
   // media uploads (POST /api/media, auth-gated; local files served at /media)
   if (enabled.has("media") && store) {
@@ -171,8 +175,8 @@ async function startApp() {
     app.use(await (await addonMod("media")).mediaRouter({ requireAuth, dir: path.join(__dirname, "media") }));
   }
 
-  // markdown pages (/<slug> ← pages/<slug>.md) — mounted last, so app routes win
-  // blog posts (/blog, /blog/<slug>, /category, /tag, /feed.xml) — before pages so /blog wins; renders in the same theme.
+  // markdown pages (/<slug> ← pages/<slug>.md) — mounted last, so app routes win
+  // blog posts (/blog, /blog/<slug>, /category, /tag, /feed.xml) — before pages so /blog wins; renders in the same theme.
   if (enabled.has("posts")) app.use(await (await addonMod("posts")).postsRouter({ dir: path.join(__dirname, "posts"), themeDir: path.join(__dirname, "pages") }));
   if (enabled.has("pages")) app.use(await (await addonMod("pages")).pagesRouter({ dir: path.join(__dirname, "pages") }));
 
@@ -180,7 +184,14 @@ async function startApp() {
   const io = new SocketServer(server);
   if (enabled.has("realtime") && store) (await addonMod("realtime")).attachRealtime(io, { store });
 
-  // third-party add-ons — register(ctx). When auth is on, requireAuth/sessionFromReq
+  // Reload connected browsers on demand — used when a second `npm run dev` finds
+  // the app already running (see the EADDRINUSE handler below) instead of crashing.
+  app.get("/__volt/reload", (_req, res) => {
+    io.emit("volt:reload", { file: "__manual__" });
+    res.json({ ok: true });
+  });
+
+  // third-party add-ons — register(ctx). When auth is on, requireAuth/sessionFromReq
   // are provided so add-ons can gate routes by login.
   let requireAuth = null;
   let sessionFromReq = null;
@@ -196,7 +207,7 @@ async function startApp() {
     if (typeof register === "function") {
       await register({ app, express, io, store, mailer, env: process.env, requireAuth, sessionFromReq, log: (...a) => console.log(`[${name}]`, ...a) });
     } else {
-      console.warn(`[volt] add-on "${name}" not found or missing a register() export — skipped`);
+      console.warn(`[volt] add-on "${name}" not found or missing a register() export — skipped`);
     }
   }
 
@@ -204,7 +215,7 @@ async function startApp() {
   const onChange = (file) => {
     clearTimeout(timer);
     timer = setTimeout(() => {
-      console.log(`[volt] change: ${file ?? "?"} → reload`);
+      console.log(`[volt] change: ${file ?? "?"} → reload`);
       io.emit("volt:reload", { file });
     }, 80);
   };
@@ -233,7 +244,21 @@ async function startApp() {
   }
 
   const on = [...enabled];
-  server.listen(PORT, () => console.log(`⚡ Volt → http://localhost:${PORT}${on.length ? "  (add-ons: " + on.join(", ") + ")" : ""}`));
+  // If the port's taken, the app is likely already running — reload it (tell the
+  // running instance to refresh browsers) and exit, instead of an EADDRINUSE crash.
+  server.on("error", async (e) => {
+    if (e.code === "EADDRINUSE") {
+      try {
+        await fetch(`http://localhost:${PORT}/__volt/reload`);
+      } catch {
+        /* old instance without the reload route, or not ours */
+      }
+      console.log(`\n[volt] already running at http://localhost:${PORT} — reloaded it. (Stop that process, or use pm2, to restart.)`);
+      process.exit(0);
+    }
+    throw e;
+  });
+  server.listen(PORT, () => console.log(`⚡ Volt → http://localhost:${PORT}${on.length ? "  (add-ons: " + on.join(", ") + ")" : ""}`));
 }
 
 // Packages an .env's selections need, beyond what package.json already has.
@@ -257,7 +282,7 @@ function neededPackages(env) {
 function ensureDriverInstalled(driver) {
   const pkg = { mongodb: "mongodb", mongo: "mongodb", mysql: "mysql2", postgres: "pg", postgresql: "pg", pg: "pg" }[String(driver || "").toLowerCase()];
   if (!pkg || fs.existsSync(path.join(__dirname, "node_modules", pkg))) return;
-  console.log(`[volt] installing ${pkg} for the connection test…`);
+  console.log(`[volt] installing ${pkg} for the connection test…`);
   spawnSync("npm", ["install", `${pkg}@${PKG_VERSIONS[pkg] || "latest"}`], { cwd: __dirname, stdio: "inherit", shell: process.platform === "win32" });
 }
 
@@ -380,15 +405,15 @@ function startSetup() {
               server.closeIdleConnections?.();
             };
             if (added.length) {
-              console.log(`[volt] installing ${added.join(", ")}…`);
+              console.log(`[volt] installing ${added.join(", ")}…`);
               const npm = spawn("npm", ["install"], { cwd: __dirname, stdio: "inherit", shell: process.platform === "win32" });
               npm.on("error", () => handoff());
               npm.on("close", () => {
-                console.log("[volt] saved .env — starting the app…");
+                console.log("[volt] saved .env — starting the app…");
                 handoff();
               });
             } else {
-              console.log("[volt] saved .env — starting the app…");
+              console.log("[volt] saved .env — starting the app…");
               handoff();
             }
           });
@@ -406,18 +431,18 @@ function startSetup() {
   server.on("error", (e) => { if (e.code === "EADDRINUSE") { console.error(`\n[volt] Config UI port ${PORT} is in use (is the app already running?). Set CONFIG_PORT in .env or pass --port <n>.\n`); process.exit(1); } throw e; });
   server.listen(PORT, "127.0.0.1", () => {
     const url = `http://localhost:${PORT}`;
-    console.log(`\n⚡ Volt setup → ${url}`);
+    console.log(`\n⚡ Volt setup → ${url}`);
     console.log("  Configure your app; it starts automatically on Apply. (reopen later: npm run dev -- --edit)");
     const ssh = process.env.SSH_CONNECTION;
     if (ssh) {
       const host = ssh.split(" ")[2];
       const user = process.env.USER || process.env.USERNAME || "you";
-      console.log("  Remote box — the server is up here; bridge it from your LOCAL machine:");
+      console.log("  Remote box — the server is up here; bridge it from your LOCAL machine:");
       console.log(`    ssh -N -L 127.0.0.1:${PORT}:localhost:${PORT} ${user}@${host}`);
-      console.log(`  …then open ${url} on your machine (the tunnel points it here).`);
+      console.log(`  …then open ${url} on your machine (the tunnel points it here).`);
     }
     console.log("");
-    if (openBrowser(url)) console.log("  (opening your browser…)\n");
+    if (openBrowser(url)) console.log("  (opening your browser…)\n");
   });
 }
 
@@ -425,8 +450,8 @@ function readEnvFileLines() {
   return fs.existsSync(ENV_PATH) ? fs.readFileSync(ENV_PATH, "utf8").split("\n") : [];
 }
 
-// --- Studio: an ephemeral, localhost-only data browser (à la Prisma Studio).
-// Not a route in the running app — it only exists while you run `--studio`, on
+// --- Studio: an ephemeral, localhost-only data browser (à la Prisma Studio).
+// Not a route in the running app — it only exists while you run `--studio`, on
 // loopback, and disappears on Ctrl-C. Shell/SSH access is the auth. ---
 const HIDDEN_COLLECTIONS = new Set(["auth_tokens", "auth_sessions", "__voltcheck"]);
 async function startStudio() {
@@ -439,7 +464,7 @@ async function startStudio() {
   try {
     store = await (await addonMod("db")).createStore();
   } catch (e) {
-    console.error("Studio: couldn't connect the store — " + e.message);
+    console.error("Studio: couldn't connect the store — " + e.message);
     process.exit(1);
   }
   const PORT = configPort();
@@ -497,15 +522,15 @@ async function startStudio() {
   server.on("error", (e) => { if (e.code === "EADDRINUSE") { console.error(`\n[volt] Config UI port ${PORT} is in use (is the app already running?). Set CONFIG_PORT in .env or pass --port <n>.\n`); process.exit(1); } throw e; });
   server.listen(PORT, "127.0.0.1", () => {
     const url = `http://localhost:${PORT}`;
-    console.log(`\n⚡ Volt Studio → ${url}   (${store.name})`);
-    console.log("  Browse your data. localhost-only, disposable — Ctrl-C when done.");
+    console.log(`\n⚡ Volt Studio → ${url}   (${store.name})`);
+    console.log("  Browse your data. localhost-only, disposable — Ctrl-C when done.");
     const ssh = process.env.SSH_CONNECTION;
     if (ssh) {
       const host = ssh.split(" ")[2];
       const user = process.env.USER || process.env.USERNAME || "you";
-      console.log("  Remote box — from your LOCAL machine:");
+      console.log("  Remote box — from your LOCAL machine:");
       console.log(`    ssh -N -L 127.0.0.1:${PORT}:localhost:${PORT} ${user}@${host}`);
-      console.log(`  …then open ${url}.`);
+      console.log(`  …then open ${url}.`);
     }
     console.log("");
     openBrowser(url);

package/templates/guestbook/ecosystem.config.cjs

@@ -0,0 +1,5 @@
+// PM2 process config. Start under pm2 with `npm run pm2` (pm2 is fetched via npx
+// if you don't have it installed); reload cleanly with `npm run pm2:restart` (no
+// port clash), tail logs with `npm run pm2:logs`, remove with `npm run pm2:stop`.
+const { name } = require("./package.json");
+module.exports = { apps: [{ name, script: "server.js" }] };

package/templates/guestbook/package.json

@@ -7,7 +7,11 @@
   "main": "server.js",
   "scripts": {
     "start": "node server.js",
-    "dev": "node server.js"
+    "dev": "node server.js",
+    "pm2": "npx --yes pm2 start ecosystem.config.cjs",
+    "pm2:restart": "npx --yes pm2 restart ecosystem.config.cjs",
+    "pm2:stop": "npx --yes pm2 delete ecosystem.config.cjs",
+    "pm2:logs": "npx --yes pm2 logs"
   },
   "dependencies": {
     "express": "^4.22.2",

package/templates/starter/ecosystem.config.cjs

@@ -0,0 +1,5 @@
+// PM2 process config. Start under pm2 with `npm run pm2` (pm2 is fetched via npx
+// if you don't have it installed); reload cleanly with `npm run pm2:restart` (no
+// port clash), tail logs with `npm run pm2:logs`, remove with `npm run pm2:stop`.
+const { name } = require("./package.json");
+module.exports = { apps: [{ name, script: "server.js" }] };

package/templates/starter/package.json

@@ -7,7 +7,11 @@
   "main": "server.js",
   "scripts": {
     "start": "node server.js",
-    "dev": "node server.js"
+    "dev": "node server.js",
+    "pm2": "npx --yes pm2 start ecosystem.config.cjs",
+    "pm2:restart": "npx --yes pm2 restart ecosystem.config.cjs",
+    "pm2:stop": "npx --yes pm2 delete ecosystem.config.cjs",
+    "pm2:logs": "npx --yes pm2 logs"
   },
   "dependencies": {
     "express": "^4.22.2",

package/templates/starter/server.js

@@ -1,9 +1,9 @@
-// server.js — dev server with a built-in first-run setup wizard.
+// server.js — dev server with a built-in first-run setup wizard.
 //
 // First run (no .env) or `node server.js --edit` (-e) opens a disposable, local
 // config page: tick add-ons, fill settings, Apply. Apply writes .env (a
 // VOLT_ADDONS list + settings) and adds any needed packages to package.json,
-// runs npm install, then starts the app — which wires whatever .env enables.
+// runs npm install, then starts the app — which wires whatever .env enables.
 // Add-on code is bundled under .volt/addons; nothing is copied into your code.
 //
 // No build step, no env-file flag: .env is auto-loaded below.
@@ -25,7 +25,7 @@ const THEMES_DIR = path.join(__dirname, ".volt", "themes"); // bundled themes th
 const DEFAULT_PORT = 26628; // create-volt stamps this with the project's date-port
 const CONFIG_DEFAULT_PORT = 5050; // the --edit/--studio config UI's default port (its own, so it never clashes with a running app)
 
-// `--port <n>` (or --port=<n>) overrides the listen port for this run — lets
+// `--port <n>` (or --port=<n>) overrides the listen port for this run — lets
 // --edit/--studio dodge a port the running app already holds, and runs the app
 // itself on a one-off port. Explicit flag wins over PORT in .env.
 function cliPort() {
@@ -105,7 +105,7 @@ const imp = (rel) => import(pathToFileURL(path.join(__dirname, rel)).href);
 const addonMod = (n) => imp(path.join(".volt", "addons", n, "files", "lib", LIB_FILE[n]));
 
 // Built-in add-ons are wired explicitly below; everything else in VOLT_ADDONS is
-// a third-party add-on — a local .volt/addons/<name>/index.js or an installed
+// a third-party add-on — a local .volt/addons/<name>/index.js or an installed
 // npm package "volt-addon-<name>" exporting register(ctx). See /docs/plugins.
 const BUILTINS = new Set(Object.keys(LIB_FILE));
 async function loadAddon(name) {
@@ -129,7 +129,7 @@ function openBrowser(url) {
   const args = plat === "win32" ? ["/c", "start", "", url] : [url];
   try {
     const child = spawn(cmd, args, { stdio: "ignore", detached: true });
-    child.on("error", () => {}); // launcher missing — emits async, don't crash
+    child.on("error", () => {}); // launcher missing — emits async, don't crash
     child.unref();
     return true;
   } catch {
@@ -157,7 +157,7 @@ async function startApp() {
   if (enabled.has("mailer")) mailer = await (await addonMod("mailer")).createMailer();
   if (enabled.has("auth") && store && mailer) app.use((await addonMod("auth")).authRouter({ store, mailer }));
 
-  // notes — a per-user CRUD example (auth-gated, owner-scoped, db-backed)
+  // notes — a per-user CRUD example (auth-gated, owner-scoped, db-backed)
   if (enabled.has("db") && enabled.has("auth") && store) {
     const guard = (await addonMod("auth")).requireAuth(store);
     const notes = store.collection("notes");
@@ -189,7 +189,11 @@ async function startApp() {
     if (fs.existsSync(pub)) app.use(express.static(pub));
   }
 
-  app.get("/", (_req, res) => res.sendFile(path.join(__dirname, "views", "index.html")));
+  app.get("/", (_req, res, next) => {
+    // a themed home page (pages/index.md) takes over "/" — else the app's index.html
+    if (enabled.has("pages") && fs.existsSync(path.join(__dirname, "pages", "index.md"))) return next();
+    res.sendFile(path.join(__dirname, "views", "index.html"));
+  });
 
   // media uploads (POST /api/media, auth-gated; local files served at /media)
   if (enabled.has("media") && store) {
@@ -197,8 +201,8 @@ async function startApp() {
     app.use(await (await addonMod("media")).mediaRouter({ requireAuth, dir: path.join(__dirname, "media") }));
   }
 
-  // markdown pages (/<slug> ← pages/<slug>.md) — mounted last, so app routes win
-  // blog posts (/blog, /blog/<slug>, /category, /tag, /feed.xml) — before pages so /blog wins; renders in the same theme.
+  // markdown pages (/<slug> ← pages/<slug>.md) — mounted last, so app routes win
+  // blog posts (/blog, /blog/<slug>, /category, /tag, /feed.xml) — before pages so /blog wins; renders in the same theme.
   if (enabled.has("posts")) app.use(await (await addonMod("posts")).postsRouter({ dir: path.join(__dirname, "posts"), themeDir: path.join(__dirname, "pages") }));
   if (enabled.has("pages")) app.use(await (await addonMod("pages")).pagesRouter({ dir: path.join(__dirname, "pages") }));
 
@@ -206,7 +210,14 @@ async function startApp() {
   const io = new SocketServer(server);
   if (enabled.has("realtime") && store) (await addonMod("realtime")).attachRealtime(io, { store });
 
-  // third-party add-ons — register(ctx). When auth is on, requireAuth/sessionFromReq
+  // Reload connected browsers on demand — used when a second `npm run dev` finds
+  // the app already running (see the EADDRINUSE handler below) instead of crashing.
+  app.get("/__volt/reload", (_req, res) => {
+    io.emit("volt:reload", { file: "__manual__" });
+    res.json({ ok: true });
+  });
+
+  // third-party add-ons — register(ctx). When auth is on, requireAuth/sessionFromReq
   // are provided so add-ons can gate routes by login.
   let requireAuth = null;
   let sessionFromReq = null;
@@ -222,7 +233,7 @@ async function startApp() {
     if (typeof register === "function") {
       await register({ app, express, io, store, mailer, env: process.env, requireAuth, sessionFromReq, log: (...a) => console.log(`[${name}]`, ...a) });
     } else {
-      console.warn(`[volt] add-on "${name}" not found or missing a register() export — skipped`);
+      console.warn(`[volt] add-on "${name}" not found or missing a register() export — skipped`);
     }
   }
 
@@ -230,7 +241,7 @@ async function startApp() {
   const onChange = (file) => {
     clearTimeout(timer);
     timer = setTimeout(() => {
-      console.log(`[volt] change: ${file ?? "?"} → reload`);
+      console.log(`[volt] change: ${file ?? "?"} → reload`);
       io.emit("volt:reload", { file });
     }, 80);
   };
@@ -259,7 +270,21 @@ async function startApp() {
   }
 
   const on = [...enabled];
-  server.listen(PORT, () => console.log(`⚡ Volt → http://localhost:${PORT}${on.length ? "  (add-ons: " + on.join(", ") + ")" : ""}`));
+  // If the port's taken, the app is likely already running — reload it (tell the
+  // running instance to refresh browsers) and exit, instead of an EADDRINUSE crash.
+  server.on("error", async (e) => {
+    if (e.code === "EADDRINUSE") {
+      try {
+        await fetch(`http://localhost:${PORT}/__volt/reload`);
+      } catch {
+        /* old instance without the reload route, or not ours */
+      }
+      console.log(`\n[volt] already running at http://localhost:${PORT} — reloaded it. (Stop that process, or use pm2, to restart.)`);
+      process.exit(0);
+    }
+    throw e;
+  });
+  server.listen(PORT, () => console.log(`⚡ Volt → http://localhost:${PORT}${on.length ? "  (add-ons: " + on.join(", ") + ")" : ""}`));
 }
 
 // Packages an .env's selections need, beyond what package.json already has.
@@ -283,7 +308,7 @@ function neededPackages(env) {
 function ensureDriverInstalled(driver) {
   const pkg = { mongodb: "mongodb", mongo: "mongodb", mysql: "mysql2", postgres: "pg", postgresql: "pg", pg: "pg" }[String(driver || "").toLowerCase()];
   if (!pkg || fs.existsSync(path.join(__dirname, "node_modules", pkg))) return;
-  console.log(`[volt] installing ${pkg} for the connection test…`);
+  console.log(`[volt] installing ${pkg} for the connection test…`);
   spawnSync("npm", ["install", `${pkg}@${PKG_VERSIONS[pkg] || "latest"}`], { cwd: __dirname, stdio: "inherit", shell: process.platform === "win32" });
 }
 
@@ -406,15 +431,15 @@ function startSetup() {
               server.closeIdleConnections?.();
             };
             if (added.length) {
-              console.log(`[volt] installing ${added.join(", ")}…`);
+              console.log(`[volt] installing ${added.join(", ")}…`);
               const npm = spawn("npm", ["install"], { cwd: __dirname, stdio: "inherit", shell: process.platform === "win32" });
               npm.on("error", () => handoff());
               npm.on("close", () => {
-                console.log("[volt] saved .env — starting the app…");
+                console.log("[volt] saved .env — starting the app…");
                 handoff();
               });
             } else {
-              console.log("[volt] saved .env — starting the app…");
+              console.log("[volt] saved .env — starting the app…");
               handoff();
             }
           });
@@ -432,18 +457,18 @@ function startSetup() {
   server.on("error", (e) => { if (e.code === "EADDRINUSE") { console.error(`\n[volt] Config UI port ${PORT} is in use (is the app already running?). Set CONFIG_PORT in .env or pass --port <n>.\n`); process.exit(1); } throw e; });
   server.listen(PORT, "127.0.0.1", () => {
     const url = `http://localhost:${PORT}`;
-    console.log(`\n⚡ Volt setup → ${url}`);
+    console.log(`\n⚡ Volt setup → ${url}`);
     console.log("  Configure your app; it starts automatically on Apply. (reopen later: npm run dev -- --edit)");
     const ssh = process.env.SSH_CONNECTION;
     if (ssh) {
       const host = ssh.split(" ")[2];
       const user = process.env.USER || process.env.USERNAME || "you";
-      console.log("  Remote box — the server is up here; bridge it from your LOCAL machine:");
+      console.log("  Remote box — the server is up here; bridge it from your LOCAL machine:");
       console.log(`    ssh -N -L 127.0.0.1:${PORT}:localhost:${PORT} ${user}@${host}`);
-      console.log(`  …then open ${url} on your machine (the tunnel points it here).`);
+      console.log(`  …then open ${url} on your machine (the tunnel points it here).`);
     }
     console.log("");
-    if (openBrowser(url)) console.log("  (opening your browser…)\n");
+    if (openBrowser(url)) console.log("  (opening your browser…)\n");
   });
 }
 
@@ -451,8 +476,8 @@ function readEnvFileLines() {
   return fs.existsSync(ENV_PATH) ? fs.readFileSync(ENV_PATH, "utf8").split("\n") : [];
 }
 
-// --- Studio: an ephemeral, localhost-only data browser (à la Prisma Studio).
-// Not a route in the running app — it only exists while you run `--studio`, on
+// --- Studio: an ephemeral, localhost-only data browser (à la Prisma Studio).
+// Not a route in the running app — it only exists while you run `--studio`, on
 // loopback, and disappears on Ctrl-C. Shell/SSH access is the auth. ---
 const HIDDEN_COLLECTIONS = new Set(["auth_tokens", "auth_sessions", "__voltcheck"]);
 async function startStudio() {
@@ -465,7 +490,7 @@ async function startStudio() {
   try {
     store = await (await addonMod("db")).createStore();
   } catch (e) {
-    console.error("Studio: couldn't connect the store — " + e.message);
+    console.error("Studio: couldn't connect the store — " + e.message);
     process.exit(1);
   }
   const PORT = configPort();
@@ -523,15 +548,15 @@ async function startStudio() {
   server.on("error", (e) => { if (e.code === "EADDRINUSE") { console.error(`\n[volt] Config UI port ${PORT} is in use (is the app already running?). Set CONFIG_PORT in .env or pass --port <n>.\n`); process.exit(1); } throw e; });
   server.listen(PORT, "127.0.0.1", () => {
     const url = `http://localhost:${PORT}`;
-    console.log(`\n⚡ Volt Studio → ${url}   (${store.name})`);
-    console.log("  Browse your data. localhost-only, disposable — Ctrl-C when done.");
+    console.log(`\n⚡ Volt Studio → ${url}   (${store.name})`);
+    console.log("  Browse your data. localhost-only, disposable — Ctrl-C when done.");
     const ssh = process.env.SSH_CONNECTION;
     if (ssh) {
       const host = ssh.split(" ")[2];
       const user = process.env.USER || process.env.USERNAME || "you";
-      console.log("  Remote box — from your LOCAL machine:");
+      console.log("  Remote box — from your LOCAL machine:");
       console.log(`    ssh -N -L 127.0.0.1:${PORT}:localhost:${PORT} ${user}@${host}`);
-      console.log(`  …then open ${url}.`);
+      console.log(`  …then open ${url}.`);
     }
     console.log("");
     openBrowser(url);