npm - create-volt - Versions diffs - 0.25.0 → 0.26.0 - Mend

create-volt 0.25.0 → 0.26.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/CHANGELOG.md +17 -0
package/addons/pages/files/lib/pages.js +60 -13
package/index.js +48 -0
package/package.json +1 -1

package/CHANGELOG.md CHANGED Viewed

@@ -4,6 +4,22 @@ 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.26.0] - 2026-06-29
+### Added
+- **Themes / shared layout for the `pages` add-on** — pages render into a layout:
+  (1) `pages/_header.html` + `_footer.html` partials (no code); (2) a local
+  `pages/_theme.js` exporting `layout({ title, head, content, meta })` (+ optional
+  `css`); (3) a third-party `volt-theme-<name>` package selected with
+  `THEME=<name>`. `create-volt create-theme <name>` scaffolds one. Resolution:
+  THEME → local `_theme.js` → built-in default.
+- **One stylesheet for page + editor** — the active theme's CSS is served at
+  `/_theme.css` (a theme's `export const css`, or `pages/_theme.css`, or the
+  default). Pages link it, and the WYSIWYG editor loads it into RTEPro's
+  `exportCSS`, so the preview matches the published page — CSS authored once.
+- **Site-wide OG image default** — `OG_IMAGE` in `.env` is the `og:image` for
+  pages without a per-page `image`.
 ## [0.25.0] - 2026-06-29
 ### Added
@@ -354,6 +370,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.26.0]: https://github.com/MIR-2025/volt/releases/tag/v0.26.0
 [0.25.0]: https://github.com/MIR-2025/volt/releases/tag/v0.25.0
 [0.24.0]: https://github.com/MIR-2025/volt/releases/tag/v0.24.0
 [0.23.0]: https://github.com/MIR-2025/volt/releases/tag/v0.23.0

package/addons/pages/files/lib/pages.js CHANGED Viewed

@@ -3,6 +3,7 @@
 // Pages are code-owned files (trusted), so their markdown HTML is served as-is.
 import fs from "node:fs";
 import path from "node:path";
+import { pathToFileURL } from "node:url";
 // express + marked are imported lazily in pagesRouter() so this module's pure
 // helpers (parseFrontMatter, isSafeSlug) load without those deps installed.
@@ -61,10 +62,11 @@ function metaHead(meta) {
     t.push(`<meta property="og:description" content="${esc(desc)}" />`);
   }
   t.push(`<meta property="og:type" content="${esc(meta.type || "website")}" />`);
-  if (meta.image) t.push(`<meta property="og:image" content="${esc(meta.image)}" />`);
+  const image = meta.image || process.env.OG_IMAGE; // per-page, else a site-wide default
+  if (image) t.push(`<meta property="og:image" content="${esc(image)}" />`);
   if (meta.url || meta.canonical) t.push(`<meta property="og:url" content="${esc(meta.url || meta.canonical)}" />`);
   if (meta.canonical) t.push(`<link rel="canonical" href="${esc(meta.canonical)}" />`);
-  t.push(`<meta name="twitter:card" content="${meta.image ? "summary_large_image" : "summary"}" />`);
+  t.push(`<meta name="twitter:card" content="${image ? "summary_large_image" : "summary"}" />`);
   if (meta.jsonld) {
     let ok = false;
     try {
@@ -78,14 +80,8 @@ function metaHead(meta) {
   return t.join("\n");
 }
-function shell(meta, inner) {
-  return `<!doctype html><html lang="en"><head><meta charset="utf-8" />
-<meta name="viewport" content="width=device-width, initial-scale=1" />
-<title>${esc(meta.title || "")}</title>
-${metaHead(meta)}
-<style>
-:root { color-scheme: light dark }
-body { max-width: 720px; margin: 2.5rem auto; padding: 0 1.1rem; font: 17px/1.7 system-ui, -apple-system, sans-serif; }
+const DEFAULT_CSS = `:root { color-scheme: light dark }
+body { max-width: 720px; margin: 0 auto; padding: 2rem 1.1rem; font: 17px/1.7 system-ui, -apple-system, sans-serif; }
 h1, h2, h3 { line-height: 1.25; margin: 1.6rem 0 .6rem }
 pre { background: #0b0d11; color: #cfe3ff; padding: 1rem; border-radius: 10px; overflow: auto }
 code { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: .9em }
@@ -93,14 +89,64 @@ code { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: .
 img { max-width: 100% } a { color: #0b67d6 }
 blockquote { border-left: 3px solid #ccc; margin: 1rem 0; padding: .2rem 1rem; opacity: .8 }
 table { border-collapse: collapse } td, th { border: 1px solid #ccc; padding: .4rem .7rem }
-</style></head><body>${inner}</body></html>`;
+header, footer { max-width: 720px; margin: 0 auto; padding: 0 1.1rem }`;
+// Built-in default theme: wraps content with optional pages/_header.html and
+// pages/_footer.html partials (read fresh each request → live edits).
+function defaultLayout(dir) {
+  const part = (f) => {
+    const p = path.join(dir, f);
+    return fs.existsSync(p) ? fs.readFileSync(p, "utf8") : "";
+  };
+  // links /_theme.css (the active theme's CSS) so the page and the editor preview
+  // share one stylesheet.
+  return ({ title, head, content }) => `<!doctype html><html lang="en"><head><meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>${esc(title)}</title>
+${head}
+<link rel="stylesheet" href="/_theme.css" /></head><body>${part("_header.html")}<main>${content}</main>${part("_footer.html")}</body></html>`;
+}
+// The active theme's CSS — a `_theme.css` override in pages/, else the default.
+function themeCss(dir) {
+  const p = path.join(dir, "_theme.css");
+  return fs.existsSync(p) ? fs.readFileSync(p, "utf8") : DEFAULT_CSS;
+}
+// Resolve the layout + its CSS. THEME=<name> → npm "volt-theme-<name>"; else a
+// local pages/_theme.js; else the built-in default. A theme may `export const css`
+// (served at /_theme.css, shared with the editor); otherwise pages/_theme.css or
+// the default CSS is used.
+async function loadTheme(dir, env) {
+  const wrap = (m) => {
+    const layout = m && (m.layout || m.default);
+    return layout ? { layout, css: m.css || themeCss(dir) } : null;
+  };
+  if (env.THEME) {
+    for (const id of [`volt-theme-${env.THEME}`, env.THEME]) {
+      try {
+        const t = wrap(await import(id));
+        if (t) return t;
+      } catch {
+        /* try next */
+      }
+    }
+  }
+  const local = path.join(dir, "_theme.js");
+  if (fs.existsSync(local)) {
+    const t = wrap(await import(pathToFileURL(local).href));
+    if (t) return t;
+  }
+  return { layout: defaultLayout(dir), css: themeCss(dir) };
 }
 export async function pagesRouter({ dir }) {
   const express = (await import("express")).default;
   const { marked } = await import("marked");
   ensure(dir);
+  const { layout, css } = await loadTheme(dir, process.env);
   const r = express.Router();
+  r.get("/_theme.css", (_req, res) => res.type("css").send(css));
   r.get("/:slug", (req, res, next) => {
     const slug = req.params.slug;
     if (!isSafeSlug(slug)) return next(); // safe slug only — no traversal
@@ -109,8 +155,9 @@ export async function pagesRouter({ dir }) {
     const { meta, body } = parseFrontMatter(fs.readFileSync(file, "utf8"));
     // `format: html` pages (e.g. from the WYSIWYG editor) are served verbatim to
     // preserve complex layouts; everything else is markdown rendered with marked.
-    const inner = meta.format === "html" ? body : marked.parse(body);
-    res.type("html").send(shell({ ...meta, title: meta.title || slug }, inner));
+    const content = meta.format === "html" ? body : marked.parse(body);
+    const m = { ...meta, title: meta.title || slug };
+    res.type("html").send(layout({ title: m.title, head: metaHead(m), content, meta: m }));
   });
   return r;
 }

package/index.js CHANGED Viewed

@@ -183,6 +183,54 @@ if (positionals[0] === "create-addon") {
   process.exit(0);
 }
+// --- `create-theme` subcommand: scaffold a publishable theme (shared layout) ---
+if (positionals[0] === "create-theme") {
+  const name = positionals[1];
+  if (!name || !/^[a-z0-9][a-z0-9-]*$/.test(name)) die(`Usage: ${cyan("create-volt create-theme <name>")} — name: lowercase letters, numbers, hyphens.`);
+  const dir = path.resolve(`volt-theme-${name}`);
+  if (fs.existsSync(dir) && !flags.has("--force")) die(`${cyan(dir)} already exists (use ${cyan("--force")}).`);
+  const THEME_INDEX = [
+    "// A Volt theme. layout(ctx) wraps page content in a full HTML document —",
+    "// this is your shared header/footer/styling for every page.",
+    "//   ctx = { title, head, content, meta }",
+    "//   - title:   page title (from front-matter)",
+    "//   - head:    SEO/social tags (OG, Twitter, canonical, JSON-LD) — put in <head>",
+    "//   - content: the rendered page HTML",
+    "//   - meta:    the front-matter object",
+    "// `css` is served at /_theme.css and shared with the WYSIWYG editor preview.",
+    "export const css = `body { font: 17px/1.7 system-ui, sans-serif; max-width: 760px; margin: 0 auto; padding: 1rem } header, footer { opacity: .75; padding: .5rem 0 }`;",
+    "",
+    "export function layout({ title, head, content }) {",
+    '  return `<!doctype html><html lang="en"><head><meta charset="utf-8" />',
+    '<meta name="viewport" content="width=device-width, initial-scale=1" />',
+    "<title>${title}</title>",
+    "${head}",
+    '<link rel="stylesheet" href="/_theme.css" />',
+    "</head><body>",
+    '  <header><strong>__NAME__</strong> &middot; <a href="/">Home</a></header>',
+    "  <main>${content}</main>",
+    "  <footer><small>Built with Volt</small></footer>",
+    "</body></html>`;",
+    "}",
+    "",
+  ].join("\n");
+  const THEME_README = [
+    "# volt-theme-__NAME__", "", "A [Volt](https://voltjs.com) theme — a shared layout (header/footer/styling) for `pages`.", "",
+    "## Use (in a Volt app with the pages add-on)", "", "```", "npm install volt-theme-__NAME__", "```", "",
+    "Then set `THEME=__NAME__` in `.env` and restart. Every page renders inside this theme's `layout()`.", "",
+    "## Develop", "", "Edit `index.js` — `layout({ title, head, content, meta })` returns the full HTML document. Put `head` in `<head>` (it carries the SEO/OG/JSON-LD tags).", "", "```", "npm publish", "```", "",
+  ].join("\n");
+  fs.mkdirSync(dir, { recursive: true });
+  const pkgJson = { name: `volt-theme-${name}`, version: "0.1.0", description: `A Volt theme: ${name}`, type: "module", main: "index.js", keywords: ["volt", "volt-theme", "theme"], files: ["index.js"], license: "MIT" };
+  fs.writeFileSync(path.join(dir, "package.json"), JSON.stringify(pkgJson, null, 2) + "\n");
+  fs.writeFileSync(path.join(dir, "index.js"), THEME_INDEX.replace(/__NAME__/g, name));
+  fs.writeFileSync(path.join(dir, "README.md"), THEME_README.replace(/__NAME__/g, name));
+  console.log(`${cyan("✓ created")} ${path.relative(process.cwd(), dir) || dir} — a Volt theme.`);
+  console.log(dim(`  edit index.js (layout), then publish:  cd volt-theme-${name} && npm publish`));
+  console.log(dim(`  use it:  npm install volt-theme-${name}  then set  THEME=${name}  in .env`));
+  process.exit(0);
+}
 // --- `update` subcommand: refresh public/volt.js in the current app to the
 // version bundled with this create-volt (so `npx create-volt@latest update`
 // pulls the latest library). Only touches the library file — never the user's

package/package.json CHANGED Viewed

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