create-volt 0.34.0 → 0.36.0

package/CHANGELOG.md

@@ -4,6 +4,31 @@ 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.36.0] - 2026-06-29
+
+### Added
+- **`--port <n>` and `CONFIG_PORT`.** `--port` overrides the listen port for any
+  run; `CONFIG_PORT` in `.env` gives the `--edit`/`--studio` config UI its own
+  port, so it never collides with a running app. An in-use config port now prints
+  a clear hint instead of a raw `EADDRINUSE` stack.
+- **Hot reload watches `pages/` and `posts/`.** Editing markdown content now
+  reloads the browser (content is read per request, so the edit shows). Theme
+  files (`_theme.js`) still need a restart — ES modules cache.
+
+### Fixed
+- The `blog` + `docs` templates had drifted from `default`s `server.js`/wizard and
+  silently missed recent fixes (including the hot-reload watcher). Re-synced, with
+  a test that fails if they drift again.
+
+## [0.35.0] - 2026-06-29
+
+### Fixed
+- **Setup wizard: dependency add-ons now show as checked.** Enabling `auth` pulls
+  in `db` + `mailer` (its dependencies), which were added to `VOLT_ADDONS` but
+  whose checkboxes stayed *unchecked* — so the generated `.env` looked like it had
+  add-ons you never picked. Pulled-in dependencies now render **checked + disabled**
+  with a "required by <add-on>" note, so the checkboxes always match `VOLT_ADDONS`.
+
 ## [0.34.0] - 2026-06-29
 
 ### Added
@@ -454,6 +479,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.36.0]: https://github.com/MIR-2025/volt/releases/tag/v0.36.0
+[0.35.0]: https://github.com/MIR-2025/volt/releases/tag/v0.35.0
 [0.34.0]: https://github.com/MIR-2025/volt/releases/tag/v0.34.0
 [0.33.0]: https://github.com/MIR-2025/volt/releases/tag/v0.33.0
 [0.32.0]: https://github.com/MIR-2025/volt/releases/tag/v0.32.0

package/package.json

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

package/templates/blog/server.js

@@ -21,6 +21,24 @@ const ENV_PATH = path.join(__dirname, ".env");
 const PKG_PATH = path.join(__dirname, "package.json");
 const ADDONS_DIR = path.join(__dirname, ".volt", "addons"); // bundled add-on sources
 const DEFAULT_PORT = 26628; // create-volt stamps this with the project's date-port
+
+// `--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() {
+  const i = process.argv.indexOf("--port");
+  const raw = i > -1 ? process.argv[i + 1] : (process.argv.find((a) => a.startsWith("--port=")) || "").split("=")[1];
+  const n = Number(raw);
+  return Number.isInteger(n) && n >= 1 && n <= 65535 ? n : null;
+}
+
+// Port for the disposable config UI (--edit / --studio): --port wins, then
+// CONFIG_PORT in .env (run it on its own port so it never clashes with the app),
+// then the app's PORT, then the date-port.
+function configPort() {
+  const env = readEnvFile(); // --edit runs before loadEnv(), so read the file too
+  return cliPort() || Number(process.env.CONFIG_PORT) || Number(env.CONFIG_PORT) || Number(process.env.PORT) || Number(env.PORT) || DEFAULT_PORT;
+}
 const PKG_VERSIONS = { mongodb: "^6.21.0", mysql2: "^3.22.5", pg: "^8.22.0", nodemailer: "^6.10.1", marked: "^18.0.5", busboy: "^1.6.0", "@aws-sdk/client-s3": "^3.1075.0" };
 const LIB_FILE = { db: "store.js", mailer: "mailer.js", auth: "auth.js", realtime: "realtime.js", pages: "pages.js", posts: "posts.js", media: "media.js" };
 
@@ -101,7 +119,7 @@ function openBrowser(url) {
 
 // --- the actual app: wires whichever add-ons .env enables ---
 async function startApp() {
-  const PORT = Number(process.env.PORT) || DEFAULT_PORT;
+  const PORT = cliPort() || Number(process.env.PORT) || DEFAULT_PORT;
   const enabled = enabledFrom(process.env);
   const app = express();
   app.disable("x-powered-by");
@@ -188,7 +206,12 @@ async function startApp() {
     };
     w(dir);
   };
-  for (const d of ["views", "public"]) watchRecursive(path.join(__dirname, d));
+  // watch content dirs too (pages/posts markdown is read per request, so a
+  // browser reload shows the edit); skip dirs that don't exist.
+  for (const d of ["views", "public", "pages", "posts"]) {
+    const full = path.join(__dirname, d);
+    if (fs.existsSync(full)) watchRecursive(full);
+  }
 
   const on = [...enabled];
   server.listen(PORT, () => console.log(`⚡ Volt → http://localhost:${PORT}${on.length ? "  (add-ons: " + on.join(", ") + ")" : ""}`));
@@ -221,7 +244,7 @@ function ensureDriverInstalled(driver) {
 
 // --- the disposable setup wizard (localhost only) ---
 function startSetup() {
-  const PORT = Number(process.env.PORT) || Number(readEnvFile().PORT) || DEFAULT_PORT;
+  const PORT = configPort();
   const assets = {
     "/setup.js": ["text/javascript; charset=utf-8", fs.readFileSync(path.join(__dirname, "setup", "setup.js"))],
     "/volt.js": ["text/javascript; charset=utf-8", fs.readFileSync(path.join(__dirname, "public", "volt.js"))],
@@ -341,6 +364,7 @@ function startSetup() {
     res.end("not found");
   });
 
+  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}`);
@@ -379,7 +403,7 @@ async function startStudio() {
     console.error("Studio: couldn't connect the store — " + e.message);
     process.exit(1);
   }
-  const PORT = Number(process.env.PORT) || Number(readEnvFile().PORT) || DEFAULT_PORT;
+  const PORT = configPort();
   const visible = (n) => n && !HIDDEN_COLLECTIONS.has(n);
   const assets = {
     "/volt.js": ["text/javascript; charset=utf-8", fs.readFileSync(path.join(__dirname, "public", "volt.js"))],
@@ -431,6 +455,7 @@ 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})`);

package/templates/blog/setup/setup.js

@@ -25,6 +25,9 @@ const state = signal({
   s3Secret: current.S3_SECRET || "",
   s3PublicBase: current.S3_PUBLIC_BASE || "",
   port: current.PORT || String(defaultPort),
+  // detect the admin's timezone from their browser (the wizard runs here), so
+  // dates render in their zone — not the server's (usually UTC on a host).
+  tz: current.SITE_TZ || Intl.DateTimeFormat().resolvedOptions().timeZone || "",
 });
 const set = (patch) => state({ ...state(), ...patch });
 const toggle = (n) => state({ ...state(), addons: { ...state().addons, [n]: !state().addons[n] } });
@@ -42,10 +45,28 @@ function effective(s) {
   return order.filter((n) => want.has(n));
 }
 
+// which *enabled* add-ons pull in `name` as a (transitive) dependency
+function requiredBy(s, name) {
+  const causes = [];
+  for (const n of order) {
+    if (n === name || !s.addons[n]) continue;
+    const seen = new Set();
+    const visit = (x) => {
+      if (seen.has(x)) return;
+      seen.add(x);
+      (depsOf[x] || []).forEach(visit);
+    };
+    (depsOf[n] || []).forEach(visit);
+    if (seen.has(name)) causes.push(n);
+  }
+  return causes;
+}
+
 const clean = (v) => String(v).replace(/[\r\n]/g, "").trim(); // one value per line; no injection
 function genEnv(s) {
   const eff = effective(s);
   const out = [`VOLT_ADDONS=${eff.join(",")}`, `PORT=${clean(s.port)}`];
+  if (s.tz) out.push(`SITE_TZ=${clean(s.tz)}`); // admin's timezone, for date display
   if (eff.includes("db")) {
     out.push(`DB_DRIVER=${clean(s.dbDriver)}`);
     if (s.dbDriver === "mongodb") {
@@ -133,11 +154,18 @@ const field = (label, key, placeholder = "") =>
     <input class="form-control" placeholder=${placeholder} value=${() => state()[key]} oninput=${(e) => set({ [key]: e.target.value })} />
   </div>`;
 
+// A dependency pulled in by another enabled add-on shows as checked + disabled
+// (you can't turn it off while something needs it), with a "required by" note —
+// so the .env's VOLT_ADDONS always matches what the boxes show.
 const addonRow = (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)} />
+    <input class="form-check-input" type="checkbox" id=${"x-" + a.name}
+      checked=${() => eff().includes(a.name)}
+      disabled=${() => !state().addons[a.name] && eff().includes(a.name)}
+      onchange=${() => toggle(a.name)} />
     <label class="form-check-label" for=${"x-" + a.name}>
-      <span class="accent">${a.name}</span>${a.dependsOn?.length ? html` <span class="text-muted small">(needs ${a.dependsOn.join(", ")})</span>` : ""}
+      <span class="accent">${a.name}</span>${a.dependsOn?.length ? html` <span class="text-muted small">(needs ${a.dependsOn.join(", ")})</span>` : ""}${() =>
+        !state().addons[a.name] && eff().includes(a.name) ? html` <span class="text-muted small">· required by ${requiredBy(state(), a.name).join(", ")}</span>` : ""}
       <div class="small text-muted">${a.description}</div>
     </label>
   </div>`;

package/templates/default/server.js

@@ -21,6 +21,24 @@ const ENV_PATH = path.join(__dirname, ".env");
 const PKG_PATH = path.join(__dirname, "package.json");
 const ADDONS_DIR = path.join(__dirname, ".volt", "addons"); // bundled add-on sources
 const DEFAULT_PORT = 26628; // create-volt stamps this with the project's date-port
+
+// `--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() {
+  const i = process.argv.indexOf("--port");
+  const raw = i > -1 ? process.argv[i + 1] : (process.argv.find((a) => a.startsWith("--port=")) || "").split("=")[1];
+  const n = Number(raw);
+  return Number.isInteger(n) && n >= 1 && n <= 65535 ? n : null;
+}
+
+// Port for the disposable config UI (--edit / --studio): --port wins, then
+// CONFIG_PORT in .env (run it on its own port so it never clashes with the app),
+// then the app's PORT, then the date-port.
+function configPort() {
+  const env = readEnvFile(); // --edit runs before loadEnv(), so read the file too
+  return cliPort() || Number(process.env.CONFIG_PORT) || Number(env.CONFIG_PORT) || Number(process.env.PORT) || Number(env.PORT) || DEFAULT_PORT;
+}
 const PKG_VERSIONS = { mongodb: "^6.21.0", mysql2: "^3.22.5", pg: "^8.22.0", nodemailer: "^6.10.1", marked: "^18.0.5", busboy: "^1.6.0", "@aws-sdk/client-s3": "^3.1075.0" };
 const LIB_FILE = { db: "store.js", mailer: "mailer.js", auth: "auth.js", realtime: "realtime.js", pages: "pages.js", posts: "posts.js", media: "media.js" };
 
@@ -101,7 +119,7 @@ function openBrowser(url) {
 
 // --- the actual app: wires whichever add-ons .env enables ---
 async function startApp() {
-  const PORT = Number(process.env.PORT) || DEFAULT_PORT;
+  const PORT = cliPort() || Number(process.env.PORT) || DEFAULT_PORT;
   const enabled = enabledFrom(process.env);
   const app = express();
   app.disable("x-powered-by");
@@ -188,7 +206,12 @@ async function startApp() {
     };
     w(dir);
   };
-  for (const d of ["views", "public"]) watchRecursive(path.join(__dirname, d));
+  // watch content dirs too (pages/posts markdown is read per request, so a
+  // browser reload shows the edit); skip dirs that don't exist.
+  for (const d of ["views", "public", "pages", "posts"]) {
+    const full = path.join(__dirname, d);
+    if (fs.existsSync(full)) watchRecursive(full);
+  }
 
   const on = [...enabled];
   server.listen(PORT, () => console.log(`⚡ Volt → http://localhost:${PORT}${on.length ? "  (add-ons: " + on.join(", ") + ")" : ""}`));
@@ -221,7 +244,7 @@ function ensureDriverInstalled(driver) {
 
 // --- the disposable setup wizard (localhost only) ---
 function startSetup() {
-  const PORT = Number(process.env.PORT) || Number(readEnvFile().PORT) || DEFAULT_PORT;
+  const PORT = configPort();
   const assets = {
     "/setup.js": ["text/javascript; charset=utf-8", fs.readFileSync(path.join(__dirname, "setup", "setup.js"))],
     "/volt.js": ["text/javascript; charset=utf-8", fs.readFileSync(path.join(__dirname, "public", "volt.js"))],
@@ -341,6 +364,7 @@ function startSetup() {
     res.end("not found");
   });
 
+  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}`);
@@ -379,7 +403,7 @@ async function startStudio() {
     console.error("Studio: couldn't connect the store — " + e.message);
     process.exit(1);
   }
-  const PORT = Number(process.env.PORT) || Number(readEnvFile().PORT) || DEFAULT_PORT;
+  const PORT = configPort();
   const visible = (n) => n && !HIDDEN_COLLECTIONS.has(n);
   const assets = {
     "/volt.js": ["text/javascript; charset=utf-8", fs.readFileSync(path.join(__dirname, "public", "volt.js"))],
@@ -431,6 +455,7 @@ 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})`);

package/templates/default/setup/setup.js

@@ -45,6 +45,23 @@ function effective(s) {
   return order.filter((n) => want.has(n));
 }
 
+// which *enabled* add-ons pull in `name` as a (transitive) dependency
+function requiredBy(s, name) {
+  const causes = [];
+  for (const n of order) {
+    if (n === name || !s.addons[n]) continue;
+    const seen = new Set();
+    const visit = (x) => {
+      if (seen.has(x)) return;
+      seen.add(x);
+      (depsOf[x] || []).forEach(visit);
+    };
+    (depsOf[n] || []).forEach(visit);
+    if (seen.has(name)) causes.push(n);
+  }
+  return causes;
+}
+
 const clean = (v) => String(v).replace(/[\r\n]/g, "").trim(); // one value per line; no injection
 function genEnv(s) {
   const eff = effective(s);
@@ -137,11 +154,18 @@ const field = (label, key, placeholder = "") =>
     <input class="form-control" placeholder=${placeholder} value=${() => state()[key]} oninput=${(e) => set({ [key]: e.target.value })} />
   </div>`;
 
+// A dependency pulled in by another enabled add-on shows as checked + disabled
+// (you can't turn it off while something needs it), with a "required by" note —
+// so the .env's VOLT_ADDONS always matches what the boxes show.
 const addonRow = (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)} />
+    <input class="form-check-input" type="checkbox" id=${"x-" + a.name}
+      checked=${() => eff().includes(a.name)}
+      disabled=${() => !state().addons[a.name] && eff().includes(a.name)}
+      onchange=${() => toggle(a.name)} />
     <label class="form-check-label" for=${"x-" + a.name}>
-      <span class="accent">${a.name}</span>${a.dependsOn?.length ? html` <span class="text-muted small">(needs ${a.dependsOn.join(", ")})</span>` : ""}
+      <span class="accent">${a.name}</span>${a.dependsOn?.length ? html` <span class="text-muted small">(needs ${a.dependsOn.join(", ")})</span>` : ""}${() =>
+        !state().addons[a.name] && eff().includes(a.name) ? html` <span class="text-muted small">· required by ${requiredBy(state(), a.name).join(", ")}</span>` : ""}
       <div class="small text-muted">${a.description}</div>
     </label>
   </div>`;

package/templates/docs/server.js

@@ -21,6 +21,24 @@ const ENV_PATH = path.join(__dirname, ".env");
 const PKG_PATH = path.join(__dirname, "package.json");
 const ADDONS_DIR = path.join(__dirname, ".volt", "addons"); // bundled add-on sources
 const DEFAULT_PORT = 26628; // create-volt stamps this with the project's date-port
+
+// `--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() {
+  const i = process.argv.indexOf("--port");
+  const raw = i > -1 ? process.argv[i + 1] : (process.argv.find((a) => a.startsWith("--port=")) || "").split("=")[1];
+  const n = Number(raw);
+  return Number.isInteger(n) && n >= 1 && n <= 65535 ? n : null;
+}
+
+// Port for the disposable config UI (--edit / --studio): --port wins, then
+// CONFIG_PORT in .env (run it on its own port so it never clashes with the app),
+// then the app's PORT, then the date-port.
+function configPort() {
+  const env = readEnvFile(); // --edit runs before loadEnv(), so read the file too
+  return cliPort() || Number(process.env.CONFIG_PORT) || Number(env.CONFIG_PORT) || Number(process.env.PORT) || Number(env.PORT) || DEFAULT_PORT;
+}
 const PKG_VERSIONS = { mongodb: "^6.21.0", mysql2: "^3.22.5", pg: "^8.22.0", nodemailer: "^6.10.1", marked: "^18.0.5", busboy: "^1.6.0", "@aws-sdk/client-s3": "^3.1075.0" };
 const LIB_FILE = { db: "store.js", mailer: "mailer.js", auth: "auth.js", realtime: "realtime.js", pages: "pages.js", posts: "posts.js", media: "media.js" };
 
@@ -101,7 +119,7 @@ function openBrowser(url) {
 
 // --- the actual app: wires whichever add-ons .env enables ---
 async function startApp() {
-  const PORT = Number(process.env.PORT) || DEFAULT_PORT;
+  const PORT = cliPort() || Number(process.env.PORT) || DEFAULT_PORT;
   const enabled = enabledFrom(process.env);
   const app = express();
   app.disable("x-powered-by");
@@ -188,7 +206,12 @@ async function startApp() {
     };
     w(dir);
   };
-  for (const d of ["views", "public"]) watchRecursive(path.join(__dirname, d));
+  // watch content dirs too (pages/posts markdown is read per request, so a
+  // browser reload shows the edit); skip dirs that don't exist.
+  for (const d of ["views", "public", "pages", "posts"]) {
+    const full = path.join(__dirname, d);
+    if (fs.existsSync(full)) watchRecursive(full);
+  }
 
   const on = [...enabled];
   server.listen(PORT, () => console.log(`⚡ Volt → http://localhost:${PORT}${on.length ? "  (add-ons: " + on.join(", ") + ")" : ""}`));
@@ -221,7 +244,7 @@ function ensureDriverInstalled(driver) {
 
 // --- the disposable setup wizard (localhost only) ---
 function startSetup() {
-  const PORT = Number(process.env.PORT) || Number(readEnvFile().PORT) || DEFAULT_PORT;
+  const PORT = configPort();
   const assets = {
     "/setup.js": ["text/javascript; charset=utf-8", fs.readFileSync(path.join(__dirname, "setup", "setup.js"))],
     "/volt.js": ["text/javascript; charset=utf-8", fs.readFileSync(path.join(__dirname, "public", "volt.js"))],
@@ -341,6 +364,7 @@ function startSetup() {
     res.end("not found");
   });
 
+  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}`);
@@ -379,7 +403,7 @@ async function startStudio() {
     console.error("Studio: couldn't connect the store — " + e.message);
     process.exit(1);
   }
-  const PORT = Number(process.env.PORT) || Number(readEnvFile().PORT) || DEFAULT_PORT;
+  const PORT = configPort();
   const visible = (n) => n && !HIDDEN_COLLECTIONS.has(n);
   const assets = {
     "/volt.js": ["text/javascript; charset=utf-8", fs.readFileSync(path.join(__dirname, "public", "volt.js"))],
@@ -431,6 +455,7 @@ 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})`);

package/templates/docs/setup/setup.js

@@ -25,6 +25,9 @@ const state = signal({
   s3Secret: current.S3_SECRET || "",
   s3PublicBase: current.S3_PUBLIC_BASE || "",
   port: current.PORT || String(defaultPort),
+  // detect the admin's timezone from their browser (the wizard runs here), so
+  // dates render in their zone — not the server's (usually UTC on a host).
+  tz: current.SITE_TZ || Intl.DateTimeFormat().resolvedOptions().timeZone || "",
 });
 const set = (patch) => state({ ...state(), ...patch });
 const toggle = (n) => state({ ...state(), addons: { ...state().addons, [n]: !state().addons[n] } });
@@ -42,10 +45,28 @@ function effective(s) {
   return order.filter((n) => want.has(n));
 }
 
+// which *enabled* add-ons pull in `name` as a (transitive) dependency
+function requiredBy(s, name) {
+  const causes = [];
+  for (const n of order) {
+    if (n === name || !s.addons[n]) continue;
+    const seen = new Set();
+    const visit = (x) => {
+      if (seen.has(x)) return;
+      seen.add(x);
+      (depsOf[x] || []).forEach(visit);
+    };
+    (depsOf[n] || []).forEach(visit);
+    if (seen.has(name)) causes.push(n);
+  }
+  return causes;
+}
+
 const clean = (v) => String(v).replace(/[\r\n]/g, "").trim(); // one value per line; no injection
 function genEnv(s) {
   const eff = effective(s);
   const out = [`VOLT_ADDONS=${eff.join(",")}`, `PORT=${clean(s.port)}`];
+  if (s.tz) out.push(`SITE_TZ=${clean(s.tz)}`); // admin's timezone, for date display
   if (eff.includes("db")) {
     out.push(`DB_DRIVER=${clean(s.dbDriver)}`);
     if (s.dbDriver === "mongodb") {
@@ -133,11 +154,18 @@ const field = (label, key, placeholder = "") =>
     <input class="form-control" placeholder=${placeholder} value=${() => state()[key]} oninput=${(e) => set({ [key]: e.target.value })} />
   </div>`;
 
+// A dependency pulled in by another enabled add-on shows as checked + disabled
+// (you can't turn it off while something needs it), with a "required by" note —
+// so the .env's VOLT_ADDONS always matches what the boxes show.
 const addonRow = (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)} />
+    <input class="form-check-input" type="checkbox" id=${"x-" + a.name}
+      checked=${() => eff().includes(a.name)}
+      disabled=${() => !state().addons[a.name] && eff().includes(a.name)}
+      onchange=${() => toggle(a.name)} />
     <label class="form-check-label" for=${"x-" + a.name}>
-      <span class="accent">${a.name}</span>${a.dependsOn?.length ? html` <span class="text-muted small">(needs ${a.dependsOn.join(", ")})</span>` : ""}
+      <span class="accent">${a.name}</span>${a.dependsOn?.length ? html` <span class="text-muted small">(needs ${a.dependsOn.join(", ")})</span>` : ""}${() =>
+        !state().addons[a.name] && eff().includes(a.name) ? html` <span class="text-muted small">· required by ${requiredBy(state(), a.name).join(", ")}</span>` : ""}
       <div class="small text-muted">${a.description}</div>
     </label>
   </div>`;

package/templates/starter/server.js

@@ -22,6 +22,24 @@ const ENV_PATH = path.join(__dirname, ".env");
 const PKG_PATH = path.join(__dirname, "package.json");
 const ADDONS_DIR = path.join(__dirname, ".volt", "addons"); // bundled add-on sources
 const DEFAULT_PORT = 26628; // create-volt stamps this with the project's date-port
+
+// `--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() {
+  const i = process.argv.indexOf("--port");
+  const raw = i > -1 ? process.argv[i + 1] : (process.argv.find((a) => a.startsWith("--port=")) || "").split("=")[1];
+  const n = Number(raw);
+  return Number.isInteger(n) && n >= 1 && n <= 65535 ? n : null;
+}
+
+// Port for the disposable config UI (--edit / --studio): --port wins, then
+// CONFIG_PORT in .env (run it on its own port so it never clashes with the app),
+// then the app's PORT, then the date-port.
+function configPort() {
+  const env = readEnvFile(); // --edit runs before loadEnv(), so read the file too
+  return cliPort() || Number(process.env.CONFIG_PORT) || Number(env.CONFIG_PORT) || Number(process.env.PORT) || Number(env.PORT) || DEFAULT_PORT;
+}
 const PKG_VERSIONS = { mongodb: "^6.21.0", mysql2: "^3.22.5", pg: "^8.22.0", nodemailer: "^6.10.1", marked: "^18.0.5", busboy: "^1.6.0", "@aws-sdk/client-s3": "^3.1075.0" };
 const LIB_FILE = { db: "store.js", mailer: "mailer.js", auth: "auth.js", realtime: "realtime.js", pages: "pages.js", posts: "posts.js", media: "media.js" };
 
@@ -102,7 +120,7 @@ function openBrowser(url) {
 
 // --- the actual app: wires whichever add-ons .env enables ---
 async function startApp() {
-  const PORT = Number(process.env.PORT) || DEFAULT_PORT;
+  const PORT = cliPort() || Number(process.env.PORT) || DEFAULT_PORT;
   const enabled = enabledFrom(process.env);
   const app = express();
   app.disable("x-powered-by");
@@ -214,7 +232,12 @@ async function startApp() {
     };
     w(dir);
   };
-  for (const d of ["views", "public"]) watchRecursive(path.join(__dirname, d));
+  // watch content dirs too (pages/posts markdown is read per request, so a
+  // browser reload shows the edit); skip dirs that don't exist.
+  for (const d of ["views", "public", "pages", "posts"]) {
+    const full = path.join(__dirname, d);
+    if (fs.existsSync(full)) watchRecursive(full);
+  }
 
   const on = [...enabled];
   server.listen(PORT, () => console.log(`⚡ Volt → http://localhost:${PORT}${on.length ? "  (add-ons: " + on.join(", ") + ")" : ""}`));
@@ -247,7 +270,7 @@ function ensureDriverInstalled(driver) {
 
 // --- the disposable setup wizard (localhost only) ---
 function startSetup() {
-  const PORT = Number(process.env.PORT) || Number(readEnvFile().PORT) || DEFAULT_PORT;
+  const PORT = configPort();
   const assets = {
     "/setup.js": ["text/javascript; charset=utf-8", fs.readFileSync(path.join(__dirname, "setup", "setup.js"))],
     "/volt.js": ["text/javascript; charset=utf-8", fs.readFileSync(path.join(__dirname, "public", "volt.js"))],
@@ -367,6 +390,7 @@ function startSetup() {
     res.end("not found");
   });
 
+  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}`);
@@ -405,7 +429,7 @@ async function startStudio() {
     console.error("Studio: couldn't connect the store — " + e.message);
     process.exit(1);
   }
-  const PORT = Number(process.env.PORT) || Number(readEnvFile().PORT) || DEFAULT_PORT;
+  const PORT = configPort();
   const visible = (n) => n && !HIDDEN_COLLECTIONS.has(n);
   const assets = {
     "/volt.js": ["text/javascript; charset=utf-8", fs.readFileSync(path.join(__dirname, "public", "volt.js"))],
@@ -457,6 +481,7 @@ 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})`);

package/templates/starter/setup/setup.js

@@ -45,6 +45,23 @@ function effective(s) {
   return order.filter((n) => want.has(n));
 }
 
+// which *enabled* add-ons pull in `name` as a (transitive) dependency
+function requiredBy(s, name) {
+  const causes = [];
+  for (const n of order) {
+    if (n === name || !s.addons[n]) continue;
+    const seen = new Set();
+    const visit = (x) => {
+      if (seen.has(x)) return;
+      seen.add(x);
+      (depsOf[x] || []).forEach(visit);
+    };
+    (depsOf[n] || []).forEach(visit);
+    if (seen.has(name)) causes.push(n);
+  }
+  return causes;
+}
+
 const clean = (v) => String(v).replace(/[\r\n]/g, "").trim(); // one value per line; no injection
 function genEnv(s) {
   const eff = effective(s);
@@ -137,11 +154,18 @@ const field = (label, key, placeholder = "") =>
     <input class="form-control" placeholder=${placeholder} value=${() => state()[key]} oninput=${(e) => set({ [key]: e.target.value })} />
   </div>`;
 
+// A dependency pulled in by another enabled add-on shows as checked + disabled
+// (you can't turn it off while something needs it), with a "required by" note —
+// so the .env's VOLT_ADDONS always matches what the boxes show.
 const addonRow = (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)} />
+    <input class="form-check-input" type="checkbox" id=${"x-" + a.name}
+      checked=${() => eff().includes(a.name)}
+      disabled=${() => !state().addons[a.name] && eff().includes(a.name)}
+      onchange=${() => toggle(a.name)} />
     <label class="form-check-label" for=${"x-" + a.name}>
-      <span class="accent">${a.name}</span>${a.dependsOn?.length ? html` <span class="text-muted small">(needs ${a.dependsOn.join(", ")})</span>` : ""}
+      <span class="accent">${a.name}</span>${a.dependsOn?.length ? html` <span class="text-muted small">(needs ${a.dependsOn.join(", ")})</span>` : ""}${() =>
+        !state().addons[a.name] && eff().includes(a.name) ? html` <span class="text-muted small">· required by ${requiredBy(state(), a.name).join(", ")}</span>` : ""}
       <div class="small text-muted">${a.description}</div>
     </label>
   </div>`;