create-volt 0.40.0 → 0.41.0

package/CHANGELOG.md

@@ -4,6 +4,17 @@ 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
@@ -537,6 +548,7 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-volt",
-  "version": "0.40.0",
+  "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

@@ -184,6 +184,13 @@ async function startApp() {
   const io = new SocketServer(server);
   if (enabled.has("realtime") && store) (await addonMod("realtime")).attachRealtime(io, { store });
 
+  // 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;
@@ -237,6 +244,20 @@ async function startApp() {
   }
 
   const on = [...enabled];
+  // 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(", ") + ")" : ""}`));
 }
 

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

@@ -184,6 +184,13 @@ async function startApp() {
   const io = new SocketServer(server);
   if (enabled.has("realtime") && store) (await addonMod("realtime")).attachRealtime(io, { store });
 
+  // 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;
@@ -237,6 +244,20 @@ async function startApp() {
   }
 
   const on = [...enabled];
+  // 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(", ") + ")" : ""}`));
 }
 

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

@@ -184,6 +184,13 @@ async function startApp() {
   const io = new SocketServer(server);
   if (enabled.has("realtime") && store) (await addonMod("realtime")).attachRealtime(io, { store });
 
+  // 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;
@@ -237,6 +244,20 @@ async function startApp() {
   }
 
   const on = [...enabled];
+  // 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(", ") + ")" : ""}`));
 }
 

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

@@ -210,6 +210,13 @@ async function startApp() {
   const io = new SocketServer(server);
   if (enabled.has("realtime") && store) (await addonMod("realtime")).attachRealtime(io, { store });
 
+  // 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;
@@ -263,6 +270,20 @@ async function startApp() {
   }
 
   const on = [...enabled];
+  // 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(", ") + ")" : ""}`));
 }