create-spark-html-app 0.8.2 → 0.9.0

package/README.md

@@ -1,6 +1,6 @@
 # create-spark-html-app
 
-Scaffold a [Spark](https://github.com/wilkinnovo/spark) app in seconds — a
+Scaffold a [Spark](https://github.com/wilkinnovo/spark-html) app in seconds — a
 Bun-powered project (dev / build / preview via `spark-html-bun`) wired to
 `spark-html` with live, reactive **Spark** components.
 
@@ -24,6 +24,24 @@ Run it with no name to be prompted:
 bunx create-spark-html-app@latest
 ```
 
+## Project types — SSR & Prerender
+
+```bash
+bunx create-spark-html-app@latest myapp              # client-only (default)
+bunx create-spark-html-app@latest myapp --ssr        # SSR with spark-ssr
+bunx create-spark-html-app@latest myapp --prerender  # static site with spark-prerender
+```
+
+Without a flag (on a TTY) an interactive picker asks which one you want.
+
+`--ssr` scaffolds the three-tier pattern — **pages** declare data with
+`<spark-ssr>`, **components** are pure UI via `<div import>`, **spark.json**
+holds the DB connection — plus a seeded SQLite dev database. No build step:
+`bun run dev` and it serves.
+
+`--prerender` scaffolds a minimal static site whose build writes
+fully-rendered HTML into `dist/` via `spark-prerender`.
+
 ## What you get
 
 The scaffold comes with the **whole Spark ecosystem pre-wired** — you delete
@@ -54,7 +72,8 @@ proprietary file format. Edit a component, save, and the page updates.
 ## The Spark family
 
 Small, single-purpose packages that share one philosophy: no compiler, no
-virtual DOM, no build step required. Add only what you use.
+virtual DOM, no build step required — built for humans who love hand-writing
+their web apps. Add only what you use.
 
 | Package | What it does |
 |---|---|

package/bin/index.js

@@ -27,7 +27,8 @@ import { createInterface } from 'node:readline/promises';
 import { stdin, stdout, argv, exit } from 'node:process';
 
 const here = dirname(fileURLToPath(import.meta.url));
-const templateDir = resolve(here, '..', 'template');
+const templateFor = (type) =>
+  resolve(here, '..', type === 'client' ? 'template' : `template-${type}`);
 
 // ── tiny ANSI palette (no chalk; one less thing to install) ───────────
 const supportsColor = stdout.isTTY && process.env.NO_COLOR === undefined;
@@ -99,6 +100,28 @@ async function prompt(question, fallback) {
   }
 }
 
+// ── project type ────────────────────────────────────────────────────────
+// Client-only (the existing default), SSR (spark-ssr), or a prerendered
+// static site (spark-prerender). Flags: --ssr / --prerender; otherwise an
+// interactive picker on a TTY.
+const TYPES = [
+  { key: 'client', label: 'Client-only (default)' },
+  { key: 'ssr', label: 'SSR (spark-ssr)' },
+  { key: 'prerender', label: 'Prerender (spark-prerender)' },
+];
+
+async function pickType() {
+  const flags = argv.slice(2);
+  if (flags.includes('--ssr')) return 'ssr';
+  if (flags.includes('--prerender')) return 'prerender';
+  if (flags.includes('--client')) return 'client';
+  if (!stdin.isTTY) return 'client';
+  stdout.write(`${c.accent('?')} Project type:\n`);
+  TYPES.forEach((t, i) => stdout.write(`  ${c.dim(String(i + 1) + ')')} ${t.label}\n`));
+  const a = (await prompt(`${c.accent('?')} Pick one ${c.dim('(1)')} `, '1')).trim();
+  return (TYPES[Number(a) - 1] || TYPES[0]).key;
+}
+
 // ── optional features ──────────────────────────────────────────────────
 // The template ships with EVERYTHING wired; excluded features are stripped
 // out of the copied files via `@spark:<name>` … `@spark:end` marker blocks
@@ -106,6 +129,7 @@ async function prompt(question, fallback) {
 const FEATURES = [
   { key: 'router', question: 'Include router (multi-page SPA)?', def: true, deps: ['spark-html-router'], files: ['public/components/about.html'] },
   { key: 'theme', question: 'Include theme (dark/light toggle)?', def: true, deps: ['spark-html-theme'], files: [] },
+  { key: 'font', question: 'Include font loading optimizer (no FOUT)?', def: true, deps: ['spark-html-font'], files: [] },
   { key: 'image', question: 'Include image optimization?', def: true, deps: ['spark-html-image'], files: ['public/components/demo-image.html', 'public/sample.jpg'] },
   { key: 'sri', question: 'Include SRI integrity checks?', def: true, deps: ['spark-html-sri'], files: [] },
   { key: 'pwa', question: 'Include PWA support (manifest + offline shell)?', def: false, deps: ['spark-html-manifest'], files: ['public/icon.png'] },
@@ -122,7 +146,7 @@ async function pickFeatures() {
     if (flags.includes(`--no-${f.key}`)) on[f.key] = false;
   }
   // Interactive only on a TTY, and only when no preset flag was given.
-  const preset = flags.some((a) => /^--(yes|all|minimal|(no-)?(router|theme|image|sri|pwa))$/.test(a));
+  const preset = flags.some((a) => /^--(yes|all|minimal|(no-)?(router|theme|font|image|sri|pwa))$/.test(a));
   if (stdin.isTTY && !preset) {
     for (const f of FEATURES) {
       const hint = f.def ? '(Y/n)' : '(y/N)';
@@ -181,10 +205,10 @@ function applyFeatures(targetDir, on) {
 
 async function main() {
   stdout.write(`\n${BOLT} ${c.bold('create-spark-html-app')}\n`);
-  stdout.write(`${c.dim('   HTML that reacts — no compiler, no virtual DOM.')}\n\n`);
+  stdout.write(`${c.dim('   HTML that reacts. Built for humans — no compiler, no virtual DOM.')}\n\n`);
 
   // 1 ─ figure out the target directory ────────────────────────────────
-  let targetArg = argv[2];
+  let targetArg = argv.slice(2).find((a) => !a.startsWith('-'));
   if (!targetArg) {
     if (!stdin.isTTY) bail('Please pass a project name: create-spark-html-app <name>');
     targetArg = await prompt(
@@ -206,11 +230,12 @@ async function main() {
     if (!/^y(es)?$/i.test(ok)) bail('Aborted — nothing was written.');
   }
 
-  // 3 ─ pick features, copy the template, strip what's excluded ────────
-  const features = await pickFeatures();
+  // 3 ─ pick the project type + features, copy the template ────────────
+  const type = await pickType();
+  const features = type === 'client' ? await pickFeatures() : {};
   mkdirSync(targetDir, { recursive: true });
-  cpSync(templateDir, targetDir, { recursive: true });
-  applyFeatures(targetDir, features);
+  cpSync(templateFor(type), targetDir, { recursive: true });
+  if (type === 'client') applyFeatures(targetDir, features);
 
   // npm renames/strips dotfiles on publish, so the template ships them
   // with safe underscore prefixes. Restore the real names here.
@@ -228,7 +253,7 @@ async function main() {
   const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
   pkg.name = projectName;
   // Drop dependencies that belong to excluded features.
-  for (const f of FEATURES) {
+  for (const f of type === 'client' ? FEATURES : []) {
     if (features[f.key]) continue;
     for (const dep of f.deps) {
       if (pkg.dependencies) delete pkg.dependencies[dep];
@@ -247,7 +272,8 @@ async function main() {
     const deps = pkg[group];
     if (!deps) continue;
     for (const name of Object.keys(deps)) {
-      if (name !== 'spark-html' && !name.startsWith('spark-html-') && name !== 'spark-prerender') continue;
+      if (name !== 'spark-html' && !name.startsWith('spark-html-')
+        && name !== 'spark-prerender' && name !== 'spark-ssr') continue;
       const range = await latestRange(name);
       if (range) {
         deps[name] = range;
@@ -259,13 +285,16 @@ async function main() {
 
   // 5 ─ celebrate + print next steps ───────────────────────────────────
   const rel = relative(process.cwd(), targetDir) || '.';
-  const picked = FEATURES.filter((f) => features[f.key]).map((f) => f.key).join(', ') || 'core only';
-  stdout.write(`\n${c.green('✔')} Scaffolded ${c.bold(projectName)} in ${c.cyan(rel)} ${c.dim(`(head, persist, prerender, devtools + ${picked})`)}\n\n`);
+  const flavor = type === 'ssr' ? 'SSR — spark-ssr, zero config, no build'
+    : type === 'prerender' ? 'prerendered static site — spark-prerender'
+    : `head, persist, prerender, devtools + ${FEATURES.filter((f) => features[f.key]).map((f) => f.key).join(', ') || 'core only'}`;
+  stdout.write(`\n${c.green('✔')} Scaffolded ${c.bold(projectName)} in ${c.cyan(rel)} ${c.dim(`(${flavor})`)}\n\n`);
   stdout.write(`${c.bold('Next steps:')}\n`);
   if (rel !== '.') stdout.write(`  ${c.dim('1.')} cd ${rel}\n`);
   stdout.write(`  ${c.dim(rel !== '.' ? '2.' : '1.')} bun install\n`);
-  stdout.write(`  ${c.dim(rel !== '.' ? '3.' : '2.')} bun dev\n\n`);
-  stdout.write(`${BOLT} Then open the dev server and edit ${c.cyan('public/components/hero.html')}.\n\n`);
+  stdout.write(`  ${c.dim(rel !== '.' ? '3.' : '2.')} bun run dev\n\n`);
+  const editHint = type === 'ssr' ? 'pages/index.html' : 'public/components/hero.html';
+  stdout.write(`${BOLT} Then open the dev server and edit ${c.cyan(editHint)}.\n\n`);
 }
 
 main().catch((err) => bail(err?.message || String(err)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-spark-html-app",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "Scaffold a spark-html app — dev/build/preview on Bun",
   "type": "module",
   "bin": {
@@ -8,14 +8,16 @@
   },
   "files": [
     "bin",
-    "template"
+    "template",
+    "template-ssr",
+    "template-prerender"
   ],
   "engines": {
     "node": ">=18"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/wilkinnovo/spark.git",
+    "url": "git+https://github.com/wilkinnovo/spark-html.git",
     "directory": "packages/create-spark-html-app"
   },
   "keywords": [

package/template/README.md

@@ -1,6 +1,6 @@
 # ⚡ Spark App
 
-A starter built with [spark-html](https://github.com/wilkinnovo/spark) — single-file
+A starter built with [spark-html](https://github.com/wilkinnovo/spark-html) — single-file
 HTML components with built-in reactivity. No compiler, no virtual DOM, no build step.
 
 The scaffold is a **multi-page SPA** with client-side routing, live demos, and a
@@ -72,5 +72,5 @@ Derive values with `$:`, share state across components with `useStore(name)`, us
 `bind:value` for two-way binds, and pass props as attributes on the `import`
 placeholder.
 
-See the [full docs](https://wilkinnovo.github.io/spark/docs) for the complete
+See the [full docs](https://wilkinnovo.github.io/spark-html/docs) for the complete
 template syntax reference.

package/template/index.html

@@ -6,9 +6,9 @@
     <title>Spark App</title>
     <meta name="description" content="A reactive app built with Spark — single-file HTML components, no compiler, no virtual DOM." />
     <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>⚡</text></svg>" />
-    <link rel="preconnect" href="https://fonts.googleapis.com" />
-    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
-    <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;600;700;800&display=swap" rel="stylesheet" />
+    <!-- Fonts are injected by spark-html-font/bun (see spark.config.js):
+         preconnects, the stylesheet, and a size-adjusted fallback face so the
+         swap never moves the page. -->
     <style>
       /* Design system — the same palette and monospace type as the Spark
                website. Tokens + base + a shared card/button/input system live here in
@@ -34,7 +34,9 @@
         --spark-ink: #ffd24a;
         --danger: #ff6b6b;
         --radius: 12px;
-        --font: "JetBrains Mono", ui-monospace, monospace;
+        /* the injected --font-jetbrains-mono stack includes the fallback face;
+           the var() fallback list covers a config without the font step */
+        --font: var(--font-jetbrains-mono, "JetBrains Mono", ui-monospace, monospace);
       }
       [data-theme="light"] {
         --bg: #fff;

package/template/package.json

@@ -21,6 +21,7 @@
     "spark-html-bun": "latest",
     "spark-prerender": "latest",
     "spark-html-devtools": "latest",
-    "spark-html-image": "latest"
+    "spark-html-image": "latest",
+    "spark-html-font": "latest"
   }
 }

package/template/public/components/footer.html

@@ -1,7 +1,7 @@
 <footer class="foot">
   Edit any file in <code>public/components/</code> and save — the page updates
   instantly. Built with
-  <a href="https://github.com/wilkinnovo/spark" target="_blank" rel="noopener">Spark</a>.
+  <a href="https://github.com/wilkinnovo/spark-html" target="_blank" rel="noopener">Spark</a>.
 </footer>
 
 <style>

package/template/spark.config.js

@@ -1,4 +1,10 @@
 import prerender from 'spark-prerender/bun';
+// @spark:theme
+import theme from 'spark-html-theme/bun';
+// @spark:end
+// @spark:font
+import font from 'spark-html-font/bun';
+// @spark:end
 // @spark:image
 import image from 'spark-html-image/bun';
 // @spark:end
@@ -26,6 +32,20 @@ import sri from 'spark-html-sri/bun';
 export default {
   pipeline: [
     prerender({ pages: ['index.html'] }),
+    // @spark:theme
+    // Bakes the tiny no-flash script into each page (dev too) so the saved /
+    // OS theme is on <html> before first paint — no wrong-theme flash on load.
+    theme(),
+    // @spark:end
+    // @spark:font
+    // Preconnect + the Google stylesheet + a size-adjusted local fallback
+    // face, baked into each page (dev too) — the font swap never moves or
+    // visibly reflows the page.
+    font({
+      fallback: ['ui-monospace', 'monospace'],
+      fonts: [{ family: 'JetBrains Mono', google: true, weights: [300, 400, 500, 600, 700, 800] }],
+    }),
+    // @spark:end
     // @spark:image
     // Every <img> in pages and components: converted to webp/avif at multiple
     // widths, srcset + width/height added (no layout shift), loading="lazy".

package/template-prerender/README.md

@@ -0,0 +1,13 @@
+# ⚡ Spark Static App
+
+A prerendered static site built with
+[spark-html](https://github.com/wilkinnovo/spark-html) + `spark-prerender`.
+Components stay single-file HTML; the build writes fully-rendered pages into
+`dist/` (plus sitemap/robots hooks) and the browser hydrates over them.
+
+```bash
+bun install
+bun run dev       # dev server with HMR
+bun run build     # prerendered static output → dist/, deploy anywhere
+bun run preview   # preview the production build
+```

package/template-prerender/_gitignore

@@ -0,0 +1,2 @@
+node_modules
+dist

package/template-prerender/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Spark Static App</title>
+    <link rel="stylesheet" href="/src/style.css" />
+  </head>
+  <body>
+    <div import="components/hero"></div>
+    <script type="module" src="/src/main.js"></script>
+  </body>
+</html>

package/template-prerender/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "spark-static-app",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "spark dev",
+    "build": "spark build",
+    "preview": "spark preview"
+  },
+  "dependencies": {
+    "spark-html": "latest"
+  },
+  "devDependencies": {
+    "spark-html-bun": "latest",
+    "spark-prerender": "latest"
+  }
+}

package/template-prerender/public/components/hero.html

@@ -0,0 +1,14 @@
+<main>
+  <h1>⚡ {greeting}</h1>
+  <p>This page is prerendered at build time — view-source on the deployed
+  site and the content is right there. Edit this component and save.</p>
+  <button onclick={cheer}>Clicked {count} times</button>
+</main>
+
+<script>
+  let greeting = 'HTML that reacts';
+  let count = 0;
+  let pageTitle = 'Spark Static App';
+  let pageDescription = 'A prerendered spark-html starter — SEO-ready static HTML that hydrates into a reactive app.';
+  function cheer() { count++; }
+</script>

package/template-prerender/spark.config.js

@@ -0,0 +1,9 @@
+import prerender from 'spark-prerender/bun';
+
+// Static site, the Spark way: `spark dev` serves components raw with HMR;
+// `spark build` copies public/, bundles the entry, then prerender() runs the
+// REAL app at build time and writes fully-rendered HTML into dist/ — crawlers
+// and AI tools read real content, the browser hydrates over it.
+export default {
+  pipeline: [prerender({ pages: ['index.html'] })],
+};

package/template-prerender/src/main.js

@@ -0,0 +1,2 @@
+import { mount } from 'spark-html';
+mount();

package/template-prerender/src/style.css

@@ -0,0 +1,3 @@
+body { font-family: system-ui, sans-serif; max-width: 36rem; margin: 4rem auto; padding: 0 1.5rem; }
+main { text-align: center; }
+button { padding: 0.5rem 1rem; cursor: pointer; }

package/template-ssr/README.md

@@ -0,0 +1,29 @@
+# ⚡ Spark SSR App
+
+SSR the Spark way — zero config, no build. The HTML template infers
+everything: `<template each="todo in todos">` means you need `todos`,
+`<spark-ssr table="todos" />` backs it with a table and the REST endpoints
+the handlers imply.
+
+## Develop
+
+```bash
+bun install
+bun run dev     # creates + seeds dev.db, then serves on :3000
+```
+
+## The three-tier pattern
+
+- **Page** — `pages/index.html` declares its data with `<spark-ssr>`
+- **Component** — `components/nav.html` is pure UI via `<div import>`
+- **Config** — `spark.json` holds the DB connection (swap sqlite → postgres
+  by changing one line)
+
+Add a page by adding a file: `pages/about.html` → `/about`,
+`pages/blog/[slug].html` → `/blog/:slug` (`:slug` binds into your queries).
+
+## Deploy
+
+```bash
+bun run build   # dist/ with a compiled single binary
+```

package/template-ssr/_gitignore

@@ -0,0 +1,4 @@
+node_modules
+dist
+dev.db
+uploads

package/template-ssr/components/nav.html

@@ -0,0 +1,4 @@
+<!-- Components are pure UI — they just render what they receive. -->
+<nav>
+  <strong>⚡ {title}</strong>
+</nav>

package/template-ssr/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "spark-ssr-app",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "bun setup.js && bun spark-ssr",
+    "start": "bun spark-ssr",
+    "build": "bun spark-ssr build"
+  },
+  "dependencies": {
+    "spark-html": "latest",
+    "spark-ssr": "latest"
+  }
+}

package/template-ssr/pages/index.css

@@ -0,0 +1,6 @@
+body { font-family: system-ui, sans-serif; max-width: 32rem; margin: 3rem auto; padding: 0 1.5rem; }
+nav { opacity: 0.7; margin-bottom: 2rem; }
+ul { padding: 0; }
+li { list-style: none; display: flex; gap: 0.5rem; align-items: center; padding: 0.35rem 0; }
+li button { margin-left: auto; }
+input[type="text"], input:not([type]) { padding: 0.4rem 0.6rem; }

package/template-ssr/pages/index.html

@@ -0,0 +1,19 @@
+<div import="/components/nav" title="Tasks"></div>
+
+<h1>Tasks</h1>
+
+<template await="todos">
+  <input bind:value="draft" placeholder="New task">
+  <button onclick={add}>Add</button>
+  <ul>
+    <template each="todo in todos">
+      <li>
+        <input type="checkbox" bind:checked="todo.done" onchange={patch}>
+        {todo.title}
+        <button onclick={remove}>✕</button>
+      </li>
+    </template>
+  </ul>
+</template>
+
+<spark-ssr table="todos" />

package/template-ssr/setup.js

@@ -0,0 +1,15 @@
+// One-time (idempotent) dev database setup — `bun run dev` runs it for you.
+// Swap spark.json's db to postgres:// any time; no code changes needed.
+import { Database } from 'bun:sqlite';
+
+const db = new Database('./dev.db', { create: true });
+db.run(`CREATE TABLE IF NOT EXISTS todos (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  title TEXT NOT NULL,
+  done INTEGER DEFAULT 0
+)`);
+if (db.query('SELECT COUNT(*) AS n FROM todos').get().n === 0) {
+  db.run("INSERT INTO todos (title) VALUES ('Try spark-ssr'), ('Edit pages/index.html'), ('Ship it')");
+  console.log('⚡ seeded dev.db with a few todos');
+}
+db.close();

package/template-ssr/spark.json

@@ -0,0 +1,3 @@
+{
+  "db": "sqlite://./dev.db"
+}