create-volt 0.51.0 → 0.53.0

package/CHANGELOG.md

@@ -4,6 +4,23 @@ 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
+- **Mailer accepts discrete SMTP vars.** The mailer add-on builds its transport
+  from `SMTP_HOST`/`SMTP_PORT`/`SMTP_SECURE`/`SMTP_USER`/`SMTP_PASS` when
+  `SMTP_URL` is not set (secure defaults on for port 465), and resolves the From
+  address as `MAIL_FROM` → `SMTP_FROM` → `SMTP_USER`. So a plain host/port/user/pass
+  config works without composing a URL.
+
 ## [0.51.0] - 2026-06-30
 
 ### Added
@@ -675,6 +692,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.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
 [0.49.0]: https://github.com/MIR-2025/volt/releases/tag/v0.49.0

package/addons/mailer/files/lib/mailer.js

@@ -1,20 +1,31 @@
-// mailer.js — sends email. In dev (no SMTP_URL) it prints messages to the
-// console so you can see them; in production it uses nodemailer when SMTP_URL
-// is set and the package is installed.
+// mailer.js — sends email. In dev (no SMTP config) it prints messages to the
+// console so you can see them; in production it uses nodemailer when SMTP is
+// configured — either a single SMTP_URL, or discrete SMTP_HOST/SMTP_PORT/
+// SMTP_SECURE/SMTP_USER/SMTP_PASS vars — and the package is installed.
 
 export async function createMailer() {
-  const smtp = process.env.SMTP_URL;
-  const from = process.env.MAIL_FROM || "App <no-reply@example.com>";
+  // transport: SMTP_URL wins; otherwise build it from discrete host/port vars.
+  const transportConfig = process.env.SMTP_URL
+    ? process.env.SMTP_URL
+    : process.env.SMTP_HOST
+      ? {
+          host: process.env.SMTP_HOST,
+          port: Number(process.env.SMTP_PORT) || 587,
+          secure: /^(1|true|yes|on)$/i.test(process.env.SMTP_SECURE || "") || Number(process.env.SMTP_PORT) === 465,
+          auth: process.env.SMTP_USER ? { user: process.env.SMTP_USER, pass: process.env.SMTP_PASS } : undefined,
+        }
+      : null;
+  const from = process.env.MAIL_FROM || process.env.SMTP_FROM || process.env.SMTP_USER || "App <no-reply@example.com>";
 
-  if (smtp) {
+  if (transportConfig) {
     let nodemailer;
     try {
       nodemailer = (await import("nodemailer")).default;
     } catch {
-      console.warn("[mailer] SMTP_URL set but 'nodemailer' isn't installed — using console. Run: npm install nodemailer");
+      console.warn("[mailer] SMTP configured but 'nodemailer' isn't installed — using console. Run: npm install nodemailer");
     }
     if (nodemailer) {
-      const transport = nodemailer.createTransport(smtp);
+      const transport = nodemailer.createTransport(transportConfig);
       return {
         name: "smtp",
         async send({ to, subject, text, html }) {

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.51.0",
+  "version": "0.53.0",
   "description": "Scaffold a new Volt app — no-build, signals-based UI with Socket.io hot reload.",
   "type": "module",
   "bin": {