create-volt 0.16.0 → 0.18.0

package/CHANGELOG.md

@@ -4,6 +4,31 @@ 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.18.0] - 2026-06-29
+
+### Added
+- **Volt SSR** — `volt-ssr.js`, a tiny server-side renderer: render the same
+  `html` / `h()` markup and signal values to an HTML string in Node (`${values}`
+  escaped by default, `raw()` for trusted HTML) via `renderToString`. Ships in
+  every template, so a scaffolded app can be server-rendered for SEO + fast first
+  paint and hydrate with `volt.js` on the client. The Volt site itself is now
+  built with it — marketing pages as Volt components, docs as markdown rendered
+  with `raw()`, the whole page composed by `renderToString`.
+
+## [0.17.0] - 2026-06-29
+
+### Added
+- **PaaS deploy targets** — every scaffold now ships a `Dockerfile`,
+  `.dockerignore`, `render.yaml`, `fly.toml`, and `Procfile`, so a Volt app
+  deploys to Render / Fly.io / Railway / DO App Platform (which handle the
+  server, DNS, and TLS) with config supplied as platform env vars. New
+  `/docs/deploy` guide covering the PaaS and PM2+nginx paths.
+
+### Changed
+- The server boots straight into app mode (no setup wizard) when
+  `NODE_ENV=production` or `VOLT_ADDONS` is set via env — so a container/PaaS
+  runs the app from platform env vars without a committed `.env`.
+
 ## [0.16.0] - 2026-06-29
 
 ### Added
@@ -242,6 +267,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.18.0]: https://github.com/MIR-2025/volt/releases/tag/v0.18.0
+[0.17.0]: https://github.com/MIR-2025/volt/releases/tag/v0.17.0
 [0.16.0]: https://github.com/MIR-2025/volt/releases/tag/v0.16.0
 [0.15.1]: https://github.com/MIR-2025/volt/releases/tag/v0.15.1
 [0.15.0]: https://github.com/MIR-2025/volt/releases/tag/v0.15.0

package/index.js

@@ -250,6 +250,11 @@ const shippedEnv = path.join(targetDir, "env");
 if (fs.existsSync(shippedEnv)) {
   fs.renameSync(shippedEnv, path.join(targetDir, ".env"));
 }
+// ship "dockerignore" → ".dockerignore" (same npm-safety dance)
+const shippedDockerignore = path.join(targetDir, "dockerignore");
+if (fs.existsSync(shippedDockerignore)) {
+  fs.renameSync(shippedDockerignore, path.join(targetDir, ".dockerignore"));
+}
 
 // Bundle the add-on sources so the app's setup wizard can enable them later
 // (only for templates that ship the wizard, i.e. have a setup/ dir).

package/package.json

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

package/templates/default/Dockerfile

@@ -0,0 +1,20 @@
+# Volt app — production container. Runs on Render, Fly.io, Railway, DO App
+# Platform, and any container host. They handle the server, DNS, and TLS; you
+# just set config as env vars.
+#
+# Configure via the platform's env vars (NOT a committed .env):
+#   VOLT_ADDONS=db,auth,...      DB_DRIVER=...   MONGODB_URI / DATABASE_URL
+#   MEDIA_DRIVER=s3   S3_ENDPOINT/S3_REGION/S3_BUCKET/S3_KEY/S3_SECRET   etc.
+#
+# Tip: run the local wizard first (`npm run dev`) so the add-on packages are
+# saved into package.json; commit package.json, then deploy and set the same
+# config as env vars here. NODE_ENV=production makes the app boot straight up
+# (no setup wizard).
+FROM node:22-alpine
+WORKDIR /app
+ENV NODE_ENV=production
+COPY package*.json ./
+RUN npm install --omit=dev
+COPY . .
+EXPOSE 8080
+CMD ["node", "server.js"]

package/templates/default/Procfile

@@ -0,0 +1 @@
+web: node server.js

package/templates/default/dockerignore

@@ -0,0 +1,6 @@
+node_modules
+.git
+.env
+*.log
+npm-debug.log*
+.DS_Store

package/templates/default/fly.toml

@@ -0,0 +1,15 @@
+# Fly.io — run `fly launch` (it uses the Dockerfile), then set config:
+#   fly secrets set VOLT_ADDONS=db,auth DB_DRIVER=mongodb MONGODB_URI=...
+app = "volt-app"
+
+[build]
+
+[http_service]
+  internal_port = 8080
+  force_https = true
+  auto_stop_machines = true
+  auto_start_machines = true
+
+[env]
+  PORT = "8080"
+  NODE_ENV = "production"

package/templates/default/public/volt-ssr.js

@@ -0,0 +1,63 @@
+// volt-ssr.js — server-side rendering for Volt. Renders the same html`` markup,
+// h() elements, and signal values to an HTML string in Node (no DOM), so a Volt
+// app can be fully server-rendered for SEO and hydrate interactive islands with
+// volt.js on the client.
+//
+//   import { html, h, raw, renderToString } from "./volt-ssr.js";
+//   renderToString(html`<p>${name}</p>`)   // → "<p>Ada</p>" (name is escaped)
+//
+// Authoring matches the client: html`` interpolations render as escaped text;
+// nest html``/h() nodes for structure; use raw() for trusted pre-built HTML.
+
+const VOID = new Set(["area", "base", "br", "col", "embed", "hr", "img", "input", "link", "meta", "param", "source", "track", "wbr"]);
+const esc = (s) => String(s).replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+
+// trusted, pre-rendered HTML — emitted verbatim. Use only for content you control.
+export const raw = (s) => ({ __raw: String(s) });
+
+// tagged-template markup; the literal chunks are trusted, ${values} are escaped.
+export const html = (strings, ...values) => ({ __tpl: true, strings, values });
+
+const isNode = (x) => x && typeof x === "object" && (x.__tpl || x.__raw || x.__el);
+
+// hyperscript element: h(tag, props?, ...children)
+export function h(tag, props, ...children) {
+  if (props === undefined || props === null || isNode(props) || Array.isArray(props) || typeof props !== "object") {
+    if (props !== undefined && props !== null) children.unshift(props);
+    props = {};
+  }
+  return { __el: true, tag, props, children };
+}
+
+const read = (v) => (typeof v === "function" ? v() : v); // resolve signals/thunks (once)
+
+function attrs(props) {
+  let out = "";
+  for (const [k, rawVal] of Object.entries(props)) {
+    if (k === "children" || k.startsWith("on")) continue; // event handlers don't SSR
+    const v = read(rawVal);
+    if (v == null || v === false) continue;
+    const name = k === "className" ? "class" : k;
+    out += v === true ? ` ${name}` : ` ${name}="${esc(v)}"`;
+  }
+  return out;
+}
+
+export function renderToString(node) {
+  const v = read(node);
+  if (v == null || v === false || v === true) return "";
+  if (typeof v === "string" || typeof v === "number") return esc(v);
+  if (v.__raw != null) return v.__raw;
+  if (Array.isArray(v)) return v.map(renderToString).join("");
+  if (v.__tpl) {
+    let out = v.strings[0];
+    for (let i = 0; i < v.values.length; i++) out += renderToString(v.values[i]) + v.strings[i + 1];
+    return out;
+  }
+  if (v.__el) {
+    if (typeof v.tag === "function") return renderToString(v.tag({ ...v.props, children: v.children }));
+    const open = `<${v.tag}${attrs(v.props)}>`;
+    return VOID.has(v.tag) ? open : `${open}${v.children.map(renderToString).join("")}</${v.tag}>`;
+  }
+  return esc(String(v));
+}

package/templates/default/render.yaml

@@ -0,0 +1,15 @@
+# Render blueprint — https://render.com/docs/blueprint-spec
+# Push this repo to GitHub, then in Render: New → Blueprint → pick the repo.
+# Render builds the Dockerfile, gives you HTTPS + a domain, and runs it.
+services:
+  - type: web
+    name: volt-app
+    runtime: docker
+    plan: starter
+    envVars:
+      - key: VOLT_ADDONS
+        sync: false # set your add-ons (e.g. "db,auth") in the dashboard
+      # Add the rest in the dashboard as needed:
+      #   DB_DRIVER, MONGODB_URI / DATABASE_URL,
+      #   MEDIA_DRIVER, S3_ENDPOINT/S3_REGION/S3_BUCKET/S3_KEY/S3_SECRET,
+      #   SMTP_URL, MAIL_FROM

package/templates/default/server.js

@@ -397,9 +397,13 @@ async function startStudio() {
 
 // --- gate: studio / setup (first run, --edit) / the app ---
 const editMode = process.argv.includes("--edit") || process.argv.includes("-e");
+// In production / on a PaaS there's no interactive wizard: config comes from the
+// platform's env vars (a Dockerfile sets NODE_ENV=production). Only fall back to
+// the first-run wizard when nothing is configured and we're not in production.
+const configured = fs.existsSync(ENV_PATH) || process.env.VOLT_ADDONS != null || process.env.NODE_ENV === "production";
 if (process.argv.includes("--studio")) {
   startStudio();
-} else if (editMode || !fs.existsSync(ENV_PATH)) {
+} else if (editMode || !configured) {
   startSetup();
 } else {
   loadEnv();

package/templates/guestbook/Dockerfile

@@ -0,0 +1,20 @@
+# Volt app — production container. Runs on Render, Fly.io, Railway, DO App
+# Platform, and any container host. They handle the server, DNS, and TLS; you
+# just set config as env vars.
+#
+# Configure via the platform's env vars (NOT a committed .env):
+#   VOLT_ADDONS=db,auth,...      DB_DRIVER=...   MONGODB_URI / DATABASE_URL
+#   MEDIA_DRIVER=s3   S3_ENDPOINT/S3_REGION/S3_BUCKET/S3_KEY/S3_SECRET   etc.
+#
+# Tip: run the local wizard first (`npm run dev`) so the add-on packages are
+# saved into package.json; commit package.json, then deploy and set the same
+# config as env vars here. NODE_ENV=production makes the app boot straight up
+# (no setup wizard).
+FROM node:22-alpine
+WORKDIR /app
+ENV NODE_ENV=production
+COPY package*.json ./
+RUN npm install --omit=dev
+COPY . .
+EXPOSE 8080
+CMD ["node", "server.js"]

package/templates/guestbook/Procfile

@@ -0,0 +1 @@
+web: node server.js

package/templates/guestbook/dockerignore

@@ -0,0 +1,6 @@
+node_modules
+.git
+.env
+*.log
+npm-debug.log*
+.DS_Store

package/templates/guestbook/fly.toml

@@ -0,0 +1,15 @@
+# Fly.io — run `fly launch` (it uses the Dockerfile), then set config:
+#   fly secrets set VOLT_ADDONS=db,auth DB_DRIVER=mongodb MONGODB_URI=...
+app = "volt-app"
+
+[build]
+
+[http_service]
+  internal_port = 8080
+  force_https = true
+  auto_stop_machines = true
+  auto_start_machines = true
+
+[env]
+  PORT = "8080"
+  NODE_ENV = "production"

package/templates/guestbook/public/volt-ssr.js

@@ -0,0 +1,63 @@
+// volt-ssr.js — server-side rendering for Volt. Renders the same html`` markup,
+// h() elements, and signal values to an HTML string in Node (no DOM), so a Volt
+// app can be fully server-rendered for SEO and hydrate interactive islands with
+// volt.js on the client.
+//
+//   import { html, h, raw, renderToString } from "./volt-ssr.js";
+//   renderToString(html`<p>${name}</p>`)   // → "<p>Ada</p>" (name is escaped)
+//
+// Authoring matches the client: html`` interpolations render as escaped text;
+// nest html``/h() nodes for structure; use raw() for trusted pre-built HTML.
+
+const VOID = new Set(["area", "base", "br", "col", "embed", "hr", "img", "input", "link", "meta", "param", "source", "track", "wbr"]);
+const esc = (s) => String(s).replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+
+// trusted, pre-rendered HTML — emitted verbatim. Use only for content you control.
+export const raw = (s) => ({ __raw: String(s) });
+
+// tagged-template markup; the literal chunks are trusted, ${values} are escaped.
+export const html = (strings, ...values) => ({ __tpl: true, strings, values });
+
+const isNode = (x) => x && typeof x === "object" && (x.__tpl || x.__raw || x.__el);
+
+// hyperscript element: h(tag, props?, ...children)
+export function h(tag, props, ...children) {
+  if (props === undefined || props === null || isNode(props) || Array.isArray(props) || typeof props !== "object") {
+    if (props !== undefined && props !== null) children.unshift(props);
+    props = {};
+  }
+  return { __el: true, tag, props, children };
+}
+
+const read = (v) => (typeof v === "function" ? v() : v); // resolve signals/thunks (once)
+
+function attrs(props) {
+  let out = "";
+  for (const [k, rawVal] of Object.entries(props)) {
+    if (k === "children" || k.startsWith("on")) continue; // event handlers don't SSR
+    const v = read(rawVal);
+    if (v == null || v === false) continue;
+    const name = k === "className" ? "class" : k;
+    out += v === true ? ` ${name}` : ` ${name}="${esc(v)}"`;
+  }
+  return out;
+}
+
+export function renderToString(node) {
+  const v = read(node);
+  if (v == null || v === false || v === true) return "";
+  if (typeof v === "string" || typeof v === "number") return esc(v);
+  if (v.__raw != null) return v.__raw;
+  if (Array.isArray(v)) return v.map(renderToString).join("");
+  if (v.__tpl) {
+    let out = v.strings[0];
+    for (let i = 0; i < v.values.length; i++) out += renderToString(v.values[i]) + v.strings[i + 1];
+    return out;
+  }
+  if (v.__el) {
+    if (typeof v.tag === "function") return renderToString(v.tag({ ...v.props, children: v.children }));
+    const open = `<${v.tag}${attrs(v.props)}>`;
+    return VOID.has(v.tag) ? open : `${open}${v.children.map(renderToString).join("")}</${v.tag}>`;
+  }
+  return esc(String(v));
+}

package/templates/guestbook/render.yaml

@@ -0,0 +1,15 @@
+# Render blueprint — https://render.com/docs/blueprint-spec
+# Push this repo to GitHub, then in Render: New → Blueprint → pick the repo.
+# Render builds the Dockerfile, gives you HTTPS + a domain, and runs it.
+services:
+  - type: web
+    name: volt-app
+    runtime: docker
+    plan: starter
+    envVars:
+      - key: VOLT_ADDONS
+        sync: false # set your add-ons (e.g. "db,auth") in the dashboard
+      # Add the rest in the dashboard as needed:
+      #   DB_DRIVER, MONGODB_URI / DATABASE_URL,
+      #   MEDIA_DRIVER, S3_ENDPOINT/S3_REGION/S3_BUCKET/S3_KEY/S3_SECRET,
+      #   SMTP_URL, MAIL_FROM

package/templates/starter/Dockerfile

@@ -0,0 +1,20 @@
+# Volt app — production container. Runs on Render, Fly.io, Railway, DO App
+# Platform, and any container host. They handle the server, DNS, and TLS; you
+# just set config as env vars.
+#
+# Configure via the platform's env vars (NOT a committed .env):
+#   VOLT_ADDONS=db,auth,...      DB_DRIVER=...   MONGODB_URI / DATABASE_URL
+#   MEDIA_DRIVER=s3   S3_ENDPOINT/S3_REGION/S3_BUCKET/S3_KEY/S3_SECRET   etc.
+#
+# Tip: run the local wizard first (`npm run dev`) so the add-on packages are
+# saved into package.json; commit package.json, then deploy and set the same
+# config as env vars here. NODE_ENV=production makes the app boot straight up
+# (no setup wizard).
+FROM node:22-alpine
+WORKDIR /app
+ENV NODE_ENV=production
+COPY package*.json ./
+RUN npm install --omit=dev
+COPY . .
+EXPOSE 8080
+CMD ["node", "server.js"]

package/templates/starter/Procfile

@@ -0,0 +1 @@
+web: node server.js

package/templates/starter/dockerignore

@@ -0,0 +1,6 @@
+node_modules
+.git
+.env
+*.log
+npm-debug.log*
+.DS_Store

package/templates/starter/fly.toml

@@ -0,0 +1,15 @@
+# Fly.io — run `fly launch` (it uses the Dockerfile), then set config:
+#   fly secrets set VOLT_ADDONS=db,auth DB_DRIVER=mongodb MONGODB_URI=...
+app = "volt-app"
+
+[build]
+
+[http_service]
+  internal_port = 8080
+  force_https = true
+  auto_stop_machines = true
+  auto_start_machines = true
+
+[env]
+  PORT = "8080"
+  NODE_ENV = "production"

package/templates/starter/public/volt-ssr.js

@@ -0,0 +1,63 @@
+// volt-ssr.js — server-side rendering for Volt. Renders the same html`` markup,
+// h() elements, and signal values to an HTML string in Node (no DOM), so a Volt
+// app can be fully server-rendered for SEO and hydrate interactive islands with
+// volt.js on the client.
+//
+//   import { html, h, raw, renderToString } from "./volt-ssr.js";
+//   renderToString(html`<p>${name}</p>`)   // → "<p>Ada</p>" (name is escaped)
+//
+// Authoring matches the client: html`` interpolations render as escaped text;
+// nest html``/h() nodes for structure; use raw() for trusted pre-built HTML.
+
+const VOID = new Set(["area", "base", "br", "col", "embed", "hr", "img", "input", "link", "meta", "param", "source", "track", "wbr"]);
+const esc = (s) => String(s).replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+
+// trusted, pre-rendered HTML — emitted verbatim. Use only for content you control.
+export const raw = (s) => ({ __raw: String(s) });
+
+// tagged-template markup; the literal chunks are trusted, ${values} are escaped.
+export const html = (strings, ...values) => ({ __tpl: true, strings, values });
+
+const isNode = (x) => x && typeof x === "object" && (x.__tpl || x.__raw || x.__el);
+
+// hyperscript element: h(tag, props?, ...children)
+export function h(tag, props, ...children) {
+  if (props === undefined || props === null || isNode(props) || Array.isArray(props) || typeof props !== "object") {
+    if (props !== undefined && props !== null) children.unshift(props);
+    props = {};
+  }
+  return { __el: true, tag, props, children };
+}
+
+const read = (v) => (typeof v === "function" ? v() : v); // resolve signals/thunks (once)
+
+function attrs(props) {
+  let out = "";
+  for (const [k, rawVal] of Object.entries(props)) {
+    if (k === "children" || k.startsWith("on")) continue; // event handlers don't SSR
+    const v = read(rawVal);
+    if (v == null || v === false) continue;
+    const name = k === "className" ? "class" : k;
+    out += v === true ? ` ${name}` : ` ${name}="${esc(v)}"`;
+  }
+  return out;
+}
+
+export function renderToString(node) {
+  const v = read(node);
+  if (v == null || v === false || v === true) return "";
+  if (typeof v === "string" || typeof v === "number") return esc(v);
+  if (v.__raw != null) return v.__raw;
+  if (Array.isArray(v)) return v.map(renderToString).join("");
+  if (v.__tpl) {
+    let out = v.strings[0];
+    for (let i = 0; i < v.values.length; i++) out += renderToString(v.values[i]) + v.strings[i + 1];
+    return out;
+  }
+  if (v.__el) {
+    if (typeof v.tag === "function") return renderToString(v.tag({ ...v.props, children: v.children }));
+    const open = `<${v.tag}${attrs(v.props)}>`;
+    return VOID.has(v.tag) ? open : `${open}${v.children.map(renderToString).join("")}</${v.tag}>`;
+  }
+  return esc(String(v));
+}

package/templates/starter/render.yaml

@@ -0,0 +1,15 @@
+# Render blueprint — https://render.com/docs/blueprint-spec
+# Push this repo to GitHub, then in Render: New → Blueprint → pick the repo.
+# Render builds the Dockerfile, gives you HTTPS + a domain, and runs it.
+services:
+  - type: web
+    name: volt-app
+    runtime: docker
+    plan: starter
+    envVars:
+      - key: VOLT_ADDONS
+        sync: false # set your add-ons (e.g. "db,auth") in the dashboard
+      # Add the rest in the dashboard as needed:
+      #   DB_DRIVER, MONGODB_URI / DATABASE_URL,
+      #   MEDIA_DRIVER, S3_ENDPOINT/S3_REGION/S3_BUCKET/S3_KEY/S3_SECRET,
+      #   SMTP_URL, MAIL_FROM

package/templates/starter/server.js

@@ -423,9 +423,13 @@ async function startStudio() {
 
 // --- gate: studio / setup (first run, --edit) / the app ---
 const editMode = process.argv.includes("--edit") || process.argv.includes("-e");
+// In production / on a PaaS there's no interactive wizard: config comes from the
+// platform's env vars (a Dockerfile sets NODE_ENV=production). Only fall back to
+// the first-run wizard when nothing is configured and we're not in production.
+const configured = fs.existsSync(ENV_PATH) || process.env.VOLT_ADDONS != null || process.env.NODE_ENV === "production";
 if (process.argv.includes("--studio")) {
   startStudio();
-} else if (editMode || !fs.existsSync(ENV_PATH)) {
+} else if (editMode || !configured) {
   startSetup();
 } else {
   loadEnv();