create-volt 0.21.0 → 0.22.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.22.0] - 2026-06-29
+
+### Added
+- **Third-party add-ons (plugins) — the WordPress-plugin equivalent.** Any
+  `VOLT_ADDONS` entry that is not built-in is loaded from a local
+  `.volt/addons/<name>/index.js` or an installed npm package
+  `volt-addon-<name>`, and wired via a single `register(ctx)` export
+  (ctx = app, express, io, store, mailer, env, log). Install functionality as
+  small, owned packages instead of dashboard plugins.
+  - `create-volt add <name>` — install `volt-addon-<name>` and enable it.
+  - `create-volt create-addon <name>` — scaffold a publishable add-on package.
+  - New `/docs/plugins`.
+
+### Fixed
+- `availableAddons()` tolerates add-on directories without `meta.json` (so
+  local third-party add-ons do not break the wizard).
+
 ## [0.21.0] - 2026-06-29
 
 ### Added
@@ -301,6 +318,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.22.0]: https://github.com/MIR-2025/volt/releases/tag/v0.22.0
 [0.21.0]: https://github.com/MIR-2025/volt/releases/tag/v0.21.0
 [0.20.0]: https://github.com/MIR-2025/volt/releases/tag/v0.20.0
 [0.19.0]: https://github.com/MIR-2025/volt/releases/tag/v0.19.0

package/index.js

@@ -94,9 +94,93 @@ const force = flags.has("--force");
 const dryRun = flags.has("--dry-run");
 const noGit = flags.has("--no-git");
 
-// The `add` command was replaced by `config` — catch old muscle memory.
+// Scaffolded files for `create-addon` (a publishable third-party add-on).
+const ADDON_INDEX = [
+  'import path from "node:path";',
+  'import { fileURLToPath } from "node:url";',
+  "",
+  "const __dirname = path.dirname(fileURLToPath(import.meta.url));",
+  "",
+  "// A Volt add-on. register(ctx) runs once at startup.",
+  "//   ctx = { app, io, store, mailer, env, log, express }",
+  "//   - app:     the Express app (add routes)",
+  "//   - io:      Socket.io server (if the realtime add-on is on)",
+  "//   - store:   the database store (collection(name).{put,get,all,find,delete}) (if db is on)",
+  "//   - mailer:  send mail (if the mailer add-on is on)",
+  "//   - express: the host's Express — use express.static / express.Router without installing it",
+  "export function register({ app, express, store, log }) {",
+  '  // serve this add-on\'s frontend assets (public/) at /__NAME__',
+  '  app.use("/__NAME__", express.static(path.join(__dirname, "public")));',
+  "",
+  "  // a tiny example API",
+  '  app.get("/api/__NAME__/ping", (_req, res) => res.json({ ok: true, addon: "__NAME__" }));',
+  "",
+  '  log("ready");',
+  "}",
+  "",
+].join("\n");
+
+const ADDON_README = [
+  "# volt-addon-__NAME__",
+  "",
+  "A [Volt](https://voltjs.com) add-on.",
+  "",
+  "## Install (inside a Volt app)",
+  "",
+  "```",
+  "npx create-volt add __NAME__",
+  "```",
+  "",
+  "That installs this package and adds `__NAME__` to `VOLT_ADDONS` in `.env`.",
+  "",
+  "## Develop",
+  "",
+  "Edit `index.js` — implement `register(ctx)` (see the context it receives). Then:",
+  "",
+  "```",
+  "npm publish",
+  "```",
+  "",
+].join("\n");
+
+// --- `add` subcommand: install a third-party add-on and enable it ---
 if (positionals[0] === "add") {
-  die(`${cyan("add")} was replaced by ${cyan("create-volt config")} — run that to add integrations.`);
+  const name = positionals[1];
+  if (!name) die(`Usage: ${cyan("create-volt add <name>")} — installs ${cyan("volt-addon-<name>")} and enables it (run inside a Volt app).`);
+  const cwd = process.cwd();
+  if (!fs.existsSync(path.join(cwd, "server.js"))) die(`Run ${cyan("create-volt add")} from inside a Volt app (no ${cyan("server.js")} here).`);
+  const pkg = /^(@|volt-addon-)/.test(name) ? name : `volt-addon-${name}`;
+  const short = pkg.replace(/^@[^/]+\//, "").replace(/^volt-addon-/, "");
+  console.log(dim(`Installing ${pkg}…`));
+  const res = spawnSync("npm", ["install", pkg], { cwd, stdio: "inherit", shell: process.platform === "win32" });
+  if (res.status) die(`npm install ${pkg} failed.`);
+  const envPath = path.join(cwd, ".env");
+  let env = fs.existsSync(envPath) ? fs.readFileSync(envPath, "utf8") : "";
+  const m = env.match(/^\s*VOLT_ADDONS\s*=(.*)$/m);
+  const list = (m ? m[1] : "").split(",").map((s) => s.trim()).filter(Boolean);
+  if (!list.includes(short)) list.push(short);
+  const line = `VOLT_ADDONS=${list.join(",")}`;
+  env = m ? env.replace(/^\s*VOLT_ADDONS\s*=.*$/m, line) : env.replace(/\n*$/, env ? "\n" : "") + line + "\n";
+  fs.writeFileSync(envPath, env);
+  console.log(`${cyan("✓ added")} ${short} — restart with ${cyan("npm run dev")}`);
+  process.exit(0);
+}
+
+// --- `create-addon` subcommand: scaffold a publishable third-party add-on ---
+if (positionals[0] === "create-addon") {
+  const name = positionals[1];
+  if (!name || !/^[a-z0-9][a-z0-9-]*$/.test(name)) die(`Usage: ${cyan("create-volt create-addon <name>")} — name: lowercase letters, numbers, hyphens.`);
+  const dir = path.resolve(`volt-addon-${name}`);
+  if (fs.existsSync(dir) && !flags.has("--force")) die(`${cyan(dir)} already exists (use ${cyan("--force")}).`);
+  fs.mkdirSync(path.join(dir, "public"), { recursive: true });
+  const pkgJson = { name: `volt-addon-${name}`, version: "0.1.0", description: `A Volt add-on: ${name}`, type: "module", main: "index.js", keywords: ["volt", "volt-addon"], files: ["index.js", "public"], license: "MIT" };
+  fs.writeFileSync(path.join(dir, "package.json"), JSON.stringify(pkgJson, null, 2) + "\n");
+  fs.writeFileSync(path.join(dir, "index.js"), ADDON_INDEX.replace(/__NAME__/g, name));
+  fs.writeFileSync(path.join(dir, "README.md"), ADDON_README.replace(/__NAME__/g, name));
+  console.log(`${cyan("✓ created")} ${path.relative(process.cwd(), dir) || dir} — a Volt add-on.`);
+  console.log(dim(`  edit index.js (register), then publish:  cd volt-addon-${name} && npm publish`));
+  console.log(dim(`  users install with:  npx create-volt add ${name}`));
+  process.exit(0);
 }
 
 // --- `update` subcommand: refresh public/volt.js in the current app to the

package/package.json

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

package/templates/default/server.js

@@ -43,7 +43,7 @@ function availableAddons() {
   if (!fs.existsSync(ADDONS_DIR)) return [];
   return fs
     .readdirSync(ADDONS_DIR, { withFileTypes: true })
-    .filter((e) => e.isDirectory())
+    .filter((e) => e.isDirectory() && fs.existsSync(path.join(ADDONS_DIR, e.name, "meta.json"))) // skip local 3rd-party add-ons (no meta)
     .map((e) => {
       const m = JSON.parse(fs.readFileSync(path.join(ADDONS_DIR, e.name, "meta.json"), "utf8"));
       return { name: e.name, description: m.description, dependsOn: m.dependsOn || [] };
@@ -55,9 +55,9 @@ function enabledFrom(env) {
   const metas = Object.fromEntries(availableAddons().map((a) => [a.name, a]));
   const out = new Set();
   const visit = (n) => {
-    if (!metas[n] || out.has(n)) return;
+    if (out.has(n)) return; // include third-party names too, not just bundled ones
     out.add(n);
-    for (const d of metas[n].dependsOn) visit(d);
+    for (const d of metas[n]?.dependsOn || []) visit(d);
   };
   for (const n of String(env.VOLT_ADDONS || "").split(",").map((s) => s.trim()).filter(Boolean)) visit(n);
   return out;
@@ -66,6 +66,23 @@ function enabledFrom(env) {
 const imp = (rel) => import(pathToFileURL(path.join(__dirname, rel)).href);
 const addonMod = (n) => imp(path.join(".volt", "addons", n, "files", "lib", LIB_FILE[n]));
 
+// Built-in add-ons are wired explicitly below; everything else in VOLT_ADDONS is
+// a third-party add-on — a local .volt/addons/<name>/index.js or an installed
+// npm package "volt-addon-<name>" exporting register(ctx). See /docs/plugins.
+const BUILTINS = new Set(Object.keys(LIB_FILE));
+async function loadAddon(name) {
+  const local = path.join(__dirname, ".volt", "addons", name, "index.js");
+  if (fs.existsSync(local)) return imp(path.join(".volt", "addons", name, "index.js"));
+  for (const id of [`volt-addon-${name}`, name]) {
+    try {
+      return await import(id);
+    } catch {
+      /* try next */
+    }
+  }
+  return null;
+}
+
 function openBrowser(url) {
   if (process.env.VOLT_NO_OPEN || process.argv.includes("--no-open")) return false;
   const plat = process.platform;
@@ -124,6 +141,18 @@ async function startApp() {
   const io = new SocketServer(server);
   if (enabled.has("realtime") && store) (await addonMod("realtime")).attachRealtime(io, { store });
 
+  // third-party add-ons — register(ctx) gets the app, io, store, mailer, and env
+  for (const name of enabled) {
+    if (BUILTINS.has(name)) continue;
+    const mod = await loadAddon(name);
+    const register = mod && (mod.register || mod.default);
+    if (typeof register === "function") {
+      await register({ app, express, io, store, mailer, env: process.env, log: (...a) => console.log(`[${name}]`, ...a) });
+    } else {
+      console.warn(`[volt] add-on "${name}" not found or missing a register() export — skipped`);
+    }
+  }
+
   let timer = null;
   const onChange = (file) => {
     clearTimeout(timer);

package/templates/starter/server.js

@@ -44,7 +44,7 @@ function availableAddons() {
   if (!fs.existsSync(ADDONS_DIR)) return [];
   return fs
     .readdirSync(ADDONS_DIR, { withFileTypes: true })
-    .filter((e) => e.isDirectory())
+    .filter((e) => e.isDirectory() && fs.existsSync(path.join(ADDONS_DIR, e.name, "meta.json"))) // skip local 3rd-party add-ons (no meta)
     .map((e) => {
       const m = JSON.parse(fs.readFileSync(path.join(ADDONS_DIR, e.name, "meta.json"), "utf8"));
       return { name: e.name, description: m.description, dependsOn: m.dependsOn || [] };
@@ -56,9 +56,9 @@ function enabledFrom(env) {
   const metas = Object.fromEntries(availableAddons().map((a) => [a.name, a]));
   const out = new Set();
   const visit = (n) => {
-    if (!metas[n] || out.has(n)) return;
+    if (out.has(n)) return; // include third-party names too, not just bundled ones
     out.add(n);
-    for (const d of metas[n].dependsOn) visit(d);
+    for (const d of metas[n]?.dependsOn || []) visit(d);
   };
   for (const n of String(env.VOLT_ADDONS || "").split(",").map((s) => s.trim()).filter(Boolean)) visit(n);
   return out;
@@ -67,6 +67,23 @@ function enabledFrom(env) {
 const imp = (rel) => import(pathToFileURL(path.join(__dirname, rel)).href);
 const addonMod = (n) => imp(path.join(".volt", "addons", n, "files", "lib", LIB_FILE[n]));
 
+// Built-in add-ons are wired explicitly below; everything else in VOLT_ADDONS is
+// a third-party add-on — a local .volt/addons/<name>/index.js or an installed
+// npm package "volt-addon-<name>" exporting register(ctx). See /docs/plugins.
+const BUILTINS = new Set(Object.keys(LIB_FILE));
+async function loadAddon(name) {
+  const local = path.join(__dirname, ".volt", "addons", name, "index.js");
+  if (fs.existsSync(local)) return imp(path.join(".volt", "addons", name, "index.js"));
+  for (const id of [`volt-addon-${name}`, name]) {
+    try {
+      return await import(id);
+    } catch {
+      /* try next */
+    }
+  }
+  return null;
+}
+
 function openBrowser(url) {
   if (process.env.VOLT_NO_OPEN || process.argv.includes("--no-open")) return false;
   const plat = process.platform;
@@ -150,6 +167,18 @@ async function startApp() {
   const io = new SocketServer(server);
   if (enabled.has("realtime") && store) (await addonMod("realtime")).attachRealtime(io, { store });
 
+  // third-party add-ons — register(ctx) gets the app, io, store, mailer, and env
+  for (const name of enabled) {
+    if (BUILTINS.has(name)) continue;
+    const mod = await loadAddon(name);
+    const register = mod && (mod.register || mod.default);
+    if (typeof register === "function") {
+      await register({ app, express, io, store, mailer, env: process.env, log: (...a) => console.log(`[${name}]`, ...a) });
+    } else {
+      console.warn(`[volt] add-on "${name}" not found or missing a register() export — skipped`);
+    }
+  }
+
   let timer = null;
   const onChange = (file) => {
     clearTimeout(timer);