create-volt 0.2.0 → 0.3.1

package/README.md

@@ -27,18 +27,32 @@ Edit `public/app.js` and save — the page hot-reloads itself.
 
 ## Options
 
-| Flag             | Effect                                                  |
-| ---------------- | ------------------------------------------------------- |
-| `--skip-install` | Don't run the install step (scaffold files only)        |
-| `--no-git`       | Don't initialize a git repository                       |
-| `--dry-run`      | Show what would be created without writing anything      |
-| `--force`        | Scaffold into an existing non-empty directory           |
-| `-h`, `--help`   | Show help                                               |
-| `-v`, `--version`| Print the create-volt version                           |
+| Flag              | Effect                                                  |
+| ----------------- | ------------------------------------------------------- |
+| `--port <number>` | Dev port for the app (default: derived from today's date)|
+| `--skip-install`  | Don't run the install step (scaffold files only)        |
+| `--no-git`        | Don't initialize a git repository                       |
+| `--dry-run`       | Show what would be created without writing anything      |
+| `--force`         | Scaffold into an existing non-empty directory           |
+| `-h`, `--help`    | Show help                                               |
+| `-v`, `--version` | Print the create-volt version                           |
 
 By default the new project is initialized as a git repository with one initial
 commit (skip with `--no-git`).
 
+### Dev port
+
+Each app's dev port is baked into its `server.js`. By default it's derived from
+**today's date** — two-digit year + month + two-digit day (e.g. `2026-06-28` →
+`26628`) — so apps created on different days never collide. Scaffolding more than
+one app on the same day? Give them distinct ports with `--port`:
+
+```bash
+npm create volt@latest api-app -- --port 26630
+```
+
+The runtime `PORT` env var still overrides it at launch.
+
 The installer auto-detects whichever package manager invoked it
 (npm / pnpm / yarn / bun) and uses it for `install`.
 

package/index.js

@@ -36,6 +36,7 @@ ${bold("Usage")}
   npx create-volt <project-directory> [options]
 
 ${bold("Options")}
+  --port <number>  Dev port for the app (default: derived from today's date)
   --skip-install   Don't run the package manager install step
   --no-git         Don't initialize a git repository
   --dry-run        Show what would be created without writing anything
@@ -48,10 +49,18 @@ ${bold("Example")}
   cd my-app && npm run dev
 `;
 
-// --- arg parsing ---
+// --- arg parsing (supports `--port <n>` and `--port=<n>`) ---
 const argv = process.argv.slice(2);
-const flags = new Set(argv.filter((a) => a.startsWith("-")));
-const positionals = argv.filter((a) => !a.startsWith("-"));
+const flags = new Set();
+const positionals = [];
+let portArg = null;
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (a === "--port") portArg = argv[++i];
+  else if (a.startsWith("--port=")) portArg = a.slice("--port=".length);
+  else if (a.startsWith("-")) flags.add(a);
+  else positionals.push(a);
+}
 
 if (flags.has("-h") || flags.has("--help")) {
   console.log(HELP);
@@ -67,6 +76,28 @@ const force = flags.has("--force");
 const dryRun = flags.has("--dry-run");
 const noGit = flags.has("--no-git");
 
+// Resolve the dev port: --port wins, else derive it from today's date as
+// two-digit-year + month (no leading zero) + two-digit-day (house convention),
+// so apps scaffolded on different days don't collide on the same port.
+function datePort(d) {
+  const yy = String(d.getFullYear()).slice(-2);
+  const mm = String(d.getMonth() + 1);
+  const dd = String(d.getDate()).padStart(2, "0");
+  return Number(`${yy}${mm}${dd}`);
+}
+let port;
+if (portArg != null) {
+  port = Number(portArg);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    die(`Invalid --port "${portArg}" — use a whole number between 1 and 65535.`);
+  }
+} else {
+  port = datePort(new Date());
+  if (port > 65535) {
+    die(`The date-derived port (${port}) is above 65535 — pass --port <1-65535>.`);
+  }
+}
+
 const rawName = positionals[0];
 if (!rawName) die(`Please specify a project directory:\n    ${cyan("npm create volt@latest")} ${green("<project-directory>")}`);
 
@@ -113,6 +144,7 @@ if (dryRun) {
   console.log("");
   console.log(dim(`Would ${skipInstall ? "skip dependency install" : "install dependencies"}.`));
   console.log(dim(`Would ${noGit ? "skip git init" : "initialize a git repository with an initial commit"}.`));
+  console.log(dim(`Would set the dev port to ${port}.`));
   console.log(`\n${green("✔")} Dry run complete — nothing was written.\n`);
   process.exit(0);
 }
@@ -137,6 +169,17 @@ const appPkg = JSON.parse(fs.readFileSync(appPkgPath, "utf8"));
 appPkg.name = appName;
 fs.writeFileSync(appPkgPath, JSON.stringify(appPkg, null, 2) + "\n");
 
+// --- stamp the chosen dev port into server.js + README ---
+const serverPath = path.join(targetDir, "server.js");
+fs.writeFileSync(
+  serverPath,
+  fs.readFileSync(serverPath, "utf8").replace(/(Number\(process\.env\.PORT\)\s*\|\|\s*)\d+/, `$1${port}`),
+);
+const appReadme = path.join(targetDir, "README.md");
+if (fs.existsSync(appReadme)) {
+  fs.writeFileSync(appReadme, fs.readFileSync(appReadme, "utf8").replace(/localhost:\d+/g, `localhost:${port}`));
+}
+
 const created = [
   "public/volt.js   — the Volt library (no build step)",
   "public/app.js    — your app (Counter + Todos demo)",
@@ -205,4 +248,4 @@ console.log(`\n${green("✔")} ${bold("Done!")} Next steps:\n`);
 console.log(`  ${cyan("cd")} ${projectName}`);
 if (!installed) console.log(`  ${cyan(installCmd)}`);
 console.log(`  ${cyan(runCmd)}`);
-console.log(`\nThen open ${cyan("http://localhost:26628")} and edit ${bold("public/app.js")}.\n`);
+console.log(`\nThen open ${cyan("http://localhost:" + port)} and edit ${bold("public/app.js")}.\n`);

package/package.json

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