create-volt 0.52.0 → 0.53.0

package/CHANGELOG.md

@@ -4,6 +4,14 @@ 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.53.0] - 2026-07-04
+
+### Added
+- **`create-volt env`** — writes a documented `.env.example` for a deploying admin
+  to fill in: every var grouped and commented, structural values (PORT, SITE_NAME,
+  VOLT_ADDONS…) seeded from an existing `.env`, secrets left blank. `--print` to
+  stdout, `--force` to overwrite.
+
 ## [0.52.0] - 2026-07-04
 
 ### Added
@@ -684,6 +692,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.53.0]: https://github.com/MIR-2025/volt/releases/tag/v0.53.0
 [0.52.0]: https://github.com/MIR-2025/volt/releases/tag/v0.52.0
 [0.51.0]: https://github.com/MIR-2025/volt/releases/tag/v0.51.0
 [0.50.0]: https://github.com/MIR-2025/volt/releases/tag/v0.50.0

package/index.js

@@ -318,6 +318,86 @@ if (positionals[0] === "config") {
   process.exit(res.status ?? 0);
 }
 
+// --- `env` subcommand: write a documented .env.example for a deploying admin to
+// fill in. Seeds structural (non-secret) values from an existing .env; secrets
+// stay blank. `--print` to stdout, `--force` to overwrite. ---
+if (positionals[0] === "env") {
+  const cwd = process.cwd();
+  const cur = {};
+  const envPath = path.join(cwd, ".env");
+  if (fs.existsSync(envPath)) {
+    for (const line of fs.readFileSync(envPath, "utf8").split("\n")) {
+      const m = line.match(/^\s*([A-Za-z0-9_]+)\s*=\s*(.*?)\s*$/);
+      if (m) cur[m[1]] = m[2].replace(/\s+#.*$/, "");
+    }
+  }
+  const v = (k, d = "") => cur[k] || d;
+  const tmpl = `# .env — Volt configuration. Fill in what your deployment needs, then keep this
+# file OUT of git. Generated by \`create-volt env\`. Uncomment the lines you use.
+
+# --- Core ---
+PORT=${v("PORT", "3000")}
+SITE_NAME=${v("SITE_NAME", "My Site")}
+SITE_URL=${v("SITE_URL")}                     # absolute base URL (RSS/canonical/OG), e.g. https://example.com
+# SITE_TZ=${v("SITE_TZ")}                     # IANA timezone for dates, e.g. America/New_York
+# CONFIG_PORT=5050                            # the --edit/--studio config UI's own port
+
+# --- Add-ons (comma-separated backends to enable) ---
+VOLT_ADDONS=${v("VOLT_ADDONS", "pages")}      # pages,posts,db,auth,mailer,media,realtime
+
+# --- Database (add-on: db) ---
+# DB_DRIVER=memory                            # memory | mongodb | mysql | postgres
+# MONGODB_URI=
+# MONGODB_DATABASE=
+# DATABASE_URL=                               # mysql:// or postgres:// URL
+
+# --- Email (add-on: mailer) — magic-link auth, receipts ---
+# One SMTP_URL, or discrete host/port/user/pass:
+# SMTP_URL=smtps://user:pass@smtp.host:465
+# SMTP_HOST=
+# SMTP_PORT=465
+# SMTP_SECURE=true                            # true for 465, false for 587 (STARTTLS)
+# SMTP_USER=
+# SMTP_PASS=
+# MAIL_FROM=My Site <hello@example.com>
+
+# --- Admin editor (volt-addon-editor) ---
+# ADMIN_PATH=/your-secret-path                # the gated editor lives at /<ADMIN_PATH>
+# ADMIN_EMAILS=you@example.com                # allowlist of who may log into the editor
+
+# --- Media uploads (add-on: media; needs auth) ---
+# MEDIA_DRIVER=local                          # local | s3
+# S3_ENDPOINT=
+# S3_REGION=
+# S3_BUCKET=
+# S3_KEY=
+# S3_SECRET=
+# S3_PUBLIC_BASE=
+
+# --- AI (editor "write with AI") ---
+# AI_PROVIDER=anthropic                       # anthropic | openai | gemini
+# Bring your own key:
+# ANTHROPIC_API_KEY=
+# OPENAI_API_KEY=
+# GEMINI_API_KEY=
+# — or — the hosted tier (free-capped, then pay-as-you-go):
+# VOLT_AI_TOKEN=                              # generate one in the config wizard
+# VOLT_AI_GATEWAY=https://voltjs.com/api/ai
+`;
+  if (flags.has("--print")) {
+    process.stdout.write(tmpl);
+    process.exit(0);
+  }
+  const out = path.join(cwd, ".env.example");
+  if (fs.existsSync(out) && !flags.has("--force")) {
+    die(`${cyan(".env.example")} already exists — pass ${cyan("--force")} to overwrite, or ${cyan("--print")} for stdout.`);
+  }
+  fs.writeFileSync(out, tmpl);
+  console.log(`\n${green("✔")} Wrote ${bold(".env.example")} — a documented template for a deploying admin.`);
+  console.log(dim(`  Copy it to .env on the server and fill in the values you need; secrets stay blank here.`));
+  process.exit(0);
+}
+
 // Write imported markdown pages to disk and print a summary (shared by both importers).
 function emitImported(imported, stats, outDir) {
   fs.mkdirSync(outDir, { recursive: true });

package/package.json

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