create-spark-html-app 0.5.6 → 0.7.0

package/README.md

@@ -25,11 +25,30 @@ Run it with no name to be prompted:
 npm create spark-html-app@latest
 ```
 
-The scaffold is a **multi-page SPA** with client-side routing (`spark-html-router`),
-reactive counters, todo lists with two-way binding and keyed reconciliation,
-slot-based composition, async declarative loading states, and shared stores
-with derived values — all in the same monospace dark/light design as the
-[Spark website](https://wilkinnovo.github.io/spark).
+## What you get
+
+The scaffold comes with the **whole Spark ecosystem pre-wired** — you delete
+what you don't need instead of wiring what you do:
+
+| Always on | Optional (prompted) |
+|-----------|---------------------|
+| `spark-html` — the runtime | `spark-html-router` — multi-page SPA *(default yes)* |
+| `spark-html-head` — reactive title/meta | `spark-html-theme` — dark/light toggle *(yes)* |
+| `spark-html-persist` — localStorage store demo | `spark-html-image` — webp/avif + srcset at build *(yes)* |
+| `spark-prerender` — SEO HTML + sitemap/robots | `spark-html-sri` — integrity checks *(yes)* |
+| `spark-html-devtools` — dev-only inspector | `spark-html-manifest` — PWA manifest + icons + offline shell *(no)* |
+
+Every included feature ships with a live demo component, ready to run.
+
+Non-interactive? Pass flags instead of answering prompts:
+
+```bash
+npx create-spark-html-app my-app --yes       # accept the defaults
+npx create-spark-html-app my-app --all       # everything on
+npx create-spark-html-app my-app --minimal   # core only
+npx create-spark-html-app my-app --pwa --no-image   # per-feature
+```
+
 Everything is plain HTML and JavaScript — no compiler, no virtual DOM, no
 proprietary file format. Edit a component, save, and the page updates.
 

package/bin/index.js

@@ -18,6 +18,8 @@ import {
   readdirSync,
   readFileSync,
   renameSync,
+  rmSync,
+  statSync,
   writeFileSync,
 } from 'node:fs';
 import { createInterface } from 'node:readline/promises';
@@ -96,6 +98,86 @@ async function prompt(question, fallback) {
   }
 }
 
+// ── optional features ──────────────────────────────────────────────────
+// The template ships with EVERYTHING wired; excluded features are stripped
+// out of the copied files via `@spark:<name>` … `@spark:end` marker blocks
+// (`@spark:!name` blocks are kept only when the feature is OFF).
+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: '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'] },
+];
+
+async function pickFeatures() {
+  const flags = argv.slice(3);
+  const on = {};
+  for (const f of FEATURES) on[f.key] = f.def;
+  if (flags.includes('--all')) for (const f of FEATURES) on[f.key] = true;
+  if (flags.includes('--minimal')) for (const f of FEATURES) on[f.key] = false;
+  for (const f of FEATURES) {
+    if (flags.includes(`--${f.key}`)) on[f.key] = true;
+    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));
+  if (stdin.isTTY && !preset) {
+    for (const f of FEATURES) {
+      const hint = f.def ? '(Y/n)' : '(y/N)';
+      const a = (await prompt(`${c.accent('?')} ${f.question} ${c.dim(hint)} `, '')).toLowerCase();
+      if (a) on[f.key] = /^y(es)?$/.test(a);
+    }
+  }
+  return on;
+}
+
+// Remove `@spark:` marker blocks for excluded features (and the marker
+// lines themselves for included ones) across every copied text file.
+function stripMarkers(text, on) {
+  const out = [];
+  let skipDepth = 0;
+  for (const line of text.split('\n')) {
+    const open = line.match(/@spark:(!?)([a-z]+)\s*(-->)?\s*$/);
+    if (open && open[2] !== 'end') {
+      const keep = open[1] === '!' ? !on[open[2]] : !!on[open[2]];
+      if (skipDepth || !keep) skipDepth++;
+      continue; // marker lines never ship
+    }
+    if (/@spark:end/.test(line)) {
+      if (skipDepth) skipDepth--;
+      continue;
+    }
+    if (!skipDepth) out.push(line);
+  }
+  return out.join('\n');
+}
+
+function walkFiles(dir) {
+  const out = [];
+  for (const name of readdirSync(dir)) {
+    const full = join(dir, name);
+    if (statSync(full).isDirectory()) out.push(...walkFiles(full));
+    else out.push(full);
+  }
+  return out;
+}
+
+function applyFeatures(targetDir, on) {
+  // 1 ─ strip marker blocks in every text file.
+  for (const file of walkFiles(targetDir)) {
+    if (!/\.(js|html|css)$/.test(file)) continue;
+    const text = readFileSync(file, 'utf8');
+    if (!text.includes('@spark:')) continue;
+    writeFileSync(file, stripMarkers(text, on), 'utf8');
+  }
+  // 2 ─ delete files that belong to excluded features.
+  for (const f of FEATURES) {
+    if (on[f.key]) continue;
+    for (const rel of f.files) rmSync(join(targetDir, rel), { force: true });
+  }
+}
+
 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`);
@@ -123,9 +205,11 @@ async function main() {
     if (!/^y(es)?$/i.test(ok)) bail('Aborted — nothing was written.');
   }
 
-  // 3 ─ copy the template ──────────────────────────────────────────────
+  // 3 ─ pick features, copy the template, strip what's excluded ────────
+  const features = await pickFeatures();
   mkdirSync(targetDir, { recursive: true });
   cpSync(templateDir, targetDir, { recursive: true });
+  applyFeatures(targetDir, features);
 
   // npm renames/strips dotfiles on publish, so the template ships them
   // with safe underscore prefixes. Restore the real names here.
@@ -142,6 +226,19 @@ async function main() {
   const pkgPath = join(targetDir, 'package.json');
   const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
   pkg.name = projectName;
+  // Drop dependencies that belong to excluded features.
+  for (const f of FEATURES) {
+    if (features[f.key]) continue;
+    for (const dep of f.deps) {
+      if (pkg.dependencies) delete pkg.dependencies[dep];
+      if (pkg.devDependencies) delete pkg.devDependencies[dep];
+    }
+  }
+  // PWA config carries the app's display name.
+  if (features.pwa) {
+    const vitePath = join(targetDir, 'vite.config.js');
+    writeFileSync(vitePath, readFileSync(vitePath, 'utf8').replace("name: 'Spark App'", `name: '${projectName}'`), 'utf8');
+  }
   // Always start on the newest published versions of the spark packages. If the
   // registry can't be reached (or a package isn't published yet), the template's
   // "latest" default still resolves on install.
@@ -161,7 +258,8 @@ async function main() {
 
   // 5 ─ celebrate + print next steps ───────────────────────────────────
   const rel = relative(process.cwd(), targetDir) || '.';
-  stdout.write(`\n${c.green('✔')} Scaffolded ${c.bold(projectName)} in ${c.cyan(rel)}\n\n`);
+  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`);
   stdout.write(`${c.bold('Next steps:')}\n`);
   if (rel !== '.') stdout.write(`  ${c.dim('1.')} cd ${rel}\n`);
   stdout.write(`  ${c.dim(rel !== '.' ? '2.' : '1.')} npm install\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-spark-html-app",
-  "version": "0.5.6",
+  "version": "0.7.0",
   "description": "Scaffold a Vite + spark-html",
   "type": "module",
   "bin": {

package/template/README.md

@@ -5,6 +5,11 @@ HTML components with built-in reactivity. No compiler, no virtual DOM, no build
 
 The scaffold is a **multi-page SPA** with client-side routing, live demos, and a
 shared design system — edit any component and save to see it update instantly.
+Depending on the options you picked at scaffold time it also wires up
+`spark-html-theme` (dark/light), `spark-html-image` (build-time webp/avif),
+`spark-html-sri` (integrity checks), and `spark-html-manifest` (PWA manifest +
+icons + offline app shell). `spark-html-head`, `spark-html-persist`,
+`spark-prerender`, and `spark-html-devtools` are always included.
 
 ## Develop
 

package/template/index.html

@@ -197,8 +197,13 @@
   <body>
     <div import="components/nav"></div>
     <main class="routes">
+      <!-- @spark:router -->
       <template route="/"><div import="components/home"></div></template>
       <template route="/about"><div import="components/about"></div></template>
+      <!-- @spark:end -->
+      <!-- @spark:!router -->
+      <div import="components/home"></div>
+      <!-- @spark:end -->
     </main>
     <div import="components/footer"></div>
 

package/template/package.json

@@ -12,11 +12,15 @@
     "spark-html": "latest",
     "spark-html-router": "latest",
     "spark-html-theme": "latest",
-    "spark-html-head": "latest"
+    "spark-html-head": "latest",
+    "spark-html-persist": "latest",
+    "spark-html-sri": "latest",
+    "spark-html-manifest": "latest"
   },
   "devDependencies": {
     "spark-prerender": "latest",
     "spark-html-devtools": "latest",
+    "spark-html-image": "latest",
     "vite": "^8.1.0"
   }
 }

package/template/public/components/demo-image.html

@@ -0,0 +1,21 @@
+<section class="card">
+  <header class="card-header">
+    <h2>Images <span class="tag">spark-html-image</span></h2>
+  </header>
+  <p class="hint">
+    A plain <code>&lt;img&gt;</code> — at build time it becomes a
+    <code>&lt;picture&gt;</code> with webp/avif srcset, width/height, and lazy
+    loading. Run <code>npm run build</code> and inspect <code>dist/</code>.
+  </p>
+
+  <img class="shot" src="/sample.jpg" alt="Sample image — optimized at build time" />
+</section>
+
+<style>
+  .shot {
+    width: 100%;
+    border-radius: 8px;
+    border: 1px solid var(--border);
+    display: block;
+  }
+</style>

package/template/public/components/demo-persist.html

@@ -0,0 +1,30 @@
+<section class="card">
+  <header class="card-header">
+    <h2>Persist <span class="tag">spark-html-persist</span></h2>
+  </header>
+  <p class="hint">
+    This store lives in <code>localStorage</code> — change it, then <b>reload the page</b>.
+  </p>
+
+  <p class="visits">You've loaded this app <b>{visits}</b> {visits === 1 ? 'time' : 'times'}.</p>
+  <label>
+    A note that survives reloads
+    <input bind:value="prefs.name" placeholder="type something, then hit reload" />
+  </label>
+</section>
+
+<script>
+  // Created in src/main.js: persist('prefs', { name: '', visits: 0 })
+  const prefs = useStore('prefs');
+  let visits = 0;
+
+  onMount(() => {
+    prefs.visits++;          // saved to localStorage immediately
+    visits = prefs.visits;   // local mirror for this render
+  });
+</script>
+
+<style>
+  .visits { font-size: 13.5px; margin-bottom: 14px; }
+  .visits b { color: var(--spark-ink); }
+</style>

package/template/public/components/demo-todo.html

@@ -1,7 +1,7 @@
 <section class="card">
   <header class="card-header">
     <h2>Todos <span class="tag">bind:value + each + $:</span></h2>
-    <span class="badge">{doneCount}/{todos.length}</span>
+    <span class="badge">{doneCount}/{todos.length} {pluralize(todos.length, 'item')}</span>
   </header>
   <p class="hint">Two-way binding, keyed reconciliation, and reactive statements in action.</p>
 
@@ -26,6 +26,8 @@
 </section>
 
 <script>
+  import { pluralize } from '../lib/format.js';
+
   let draft = '';
   let todos = [
     { id: 1, text: 'Learn Spark', done: true },

package/template/public/components/hero.html

@@ -11,18 +11,20 @@
     <button class="round" onclick="{count = Math.max(0, count - 1)}" :disabled="count <= 0" aria-label="decrement">–</button>
     <div class="readout">
       <span class="num">{count}</span>
-      <span class="sub">doubled is {doubled} · {mood}</span>
+      <span class="sub">doubled is {doubled} · {capitalize(mood)}</span>
     </div>
     <button class="round plus" onclick="{count++}" aria-label="increment">+</button>
   </div>
 
   <p class="store-line">
     You've struck the bolt <strong>{app.sparks}</strong>
-    time{app.sparks === 1 ? '' : 's'} — that lives in a shared store.
+    {pluralize(app.sparks, 'time')} — that lives in a shared store.
   </p>
 </header>
 
 <script>
+  import { capitalize, pluralize } from '../lib/format.js';
+
   let count = 0;
   let igniting = false;
 

package/template/public/components/home.html

@@ -11,6 +11,13 @@
     <div import="components/demo-props"></div>
   </div>
 
+  <div class="grid">
+    <div import="components/demo-persist"></div>
+    <!-- @spark:image -->
+    <div import="components/demo-image"></div>
+    <!-- @spark:end -->
+  </div>
+
   <div import="components/demo-await"></div>
 </section>
 

package/template/public/components/nav.html

@@ -6,16 +6,22 @@
     </a>
     <div class="nav-links">
       <a href="/">Home</a>
+      <!-- @spark:router -->
       <a href="/about">About</a>
+      <!-- @spark:end -->
     </div>
+    <!-- @spark:theme -->
     <button class="theme" onclick="{theme.toggle}" title="Toggle theme">
       {theme.resolved === 'dark' ? '☾' : '☀'}
     </button>
+    <!-- @spark:end -->
   </div>
 </nav>
 
 <script>
+  // @spark:theme
   const theme = useStore('theme');
+  // @spark:end
 </script>
 
 <style>

package/template/public/lib/format.js

@@ -0,0 +1,13 @@
+export function capitalize(str) {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+export function pluralize(count, singular, plural) {
+  return count === 1 ? singular : (plural || singular + 's');
+}
+
+export function formatDate(date) {
+  return date.toLocaleDateString('en-US', {
+    year: 'numeric', month: 'short', day: 'numeric',
+  });
+}

package/template/src/main.js

@@ -1,12 +1,30 @@
 import { store } from "spark-html";
+// @spark:!router
+import { mount } from "spark-html";
+// @spark:end
+// @spark:router
 import { router } from "spark-html-router";
+// @spark:end
+// @spark:theme
 import { theme } from "spark-html-theme";
+// @spark:end
 import { head } from "spark-html-head";
+import { persist } from "spark-html-persist";
+// @spark:sri
+import { sri } from "spark-html-sri";
+// @spark:end
 import { devtools } from "spark-html-devtools";
 
 const dev = import.meta.env?.DEV;
 if (dev) devtools(); // dev only
 
+// @spark:sri
+// Subresource Integrity: verifies every component fetch against the
+// manifest the build baked into the page, and allow-lists remote URL
+// imports (TOFU). Fails open on localhost, enforces in production.
+sri();
+// @spark:end
+
 head({
   title: { "/": "Home", "/about": "About", "*": "Not found" },
   titleTemplate: (t) => `${t} · My Site`,
@@ -16,9 +34,28 @@ head({
 // Shared stores connect components without providers or prop drilling.
 store("app", { sparks: 0 });
 
+// A store that survives reloads — hydrates from localStorage on boot,
+// saves on every change (see components/demo-persist.html).
+persist("prefs", { name: "", visits: 0 });
+
+// @spark:theme
 // One-line dark/light/system theming (the ⚡ logo toggles it).
 theme();
+// @spark:end
+
+// @spark:pwa
+// PWA: manifest.webmanifest, icons, and the offline app-shell worker are
+// generated by spark-html-manifest/vite (see vite.config.js) — the worker
+// registration is injected into every built page automatically.
+// Want offline-capable CDN component imports too? See spark-html-offline
+// (a page registers one worker per scope, so pick the one you need).
+// @spark:end
 
+// @spark:router
 // Client-side router: reads <template route> blocks, intercepts <a> clicks,
 // and manages SPA navigation. Call it once — replaces mount().
 router({ devOverlay: dev, quiet: !dev });
+// @spark:end
+// @spark:!router
+mount(document.body);
+// @spark:end

package/template/vite.config.js

@@ -1,6 +1,15 @@
 import { defineConfig } from 'vite';
 import spark from 'spark-html/vite';
 import prerender from 'spark-prerender/vite';
+// @spark:image
+import image from 'spark-html-image/vite';
+// @spark:end
+// @spark:pwa
+import manifest from 'spark-html-manifest/vite';
+// @spark:end
+// @spark:sri
+import sri from 'spark-html-sri/vite';
+// @spark:end
 
 // Spark needs no build step — Vite is just a convenient dev server and
 // bundler. The plugin serves component fragments raw and full-reloads
@@ -9,11 +18,38 @@ import prerender from 'spark-prerender/vite';
 //
 // `prerender()` makes `npm run build` SEO-friendly: it runs your app at
 // build time and writes fully-rendered HTML into dist/ (crawlers and AI
-// tools read real content; the browser still hydrates over it). Remove it
-// if you don't need SEO. List every page you ship in `pages`.
+// tools read real content; the browser still hydrates over it), plus
+// sitemap.xml + robots.txt. Remove it if you don't need SEO.
 export default defineConfig({
+  optimizeDeps: {
+    // Ensure spark-html is pre-bundled so all modules share the same stores Map.
+    // Without this, file: references can create duplicate runtime instances.
+    include: ['spark-html'],
+  },
   plugins: [
     spark(),
+    // @spark:image
+    // Every <img> in pages and components: converted to webp/avif at
+    // multiple widths, wrapped in <picture> with srcset, width/height
+    // added (no layout shift), loading="lazy". Zero config.
+    image(),
+    // @spark:end
     prerender({ pages: ['index.html'] }),
+    // @spark:pwa
+    // One config → manifest.webmanifest + resized icons + <head> tags +
+    // an offline app-shell service worker (registered automatically).
+    manifest({
+      name: 'Spark App',
+      themeColor: '#ffd24a',
+      icon: 'public/icon.png',
+      offline: true,
+    }),
+    // @spark:end
+    // @spark:sri
+    // Hashes every built asset + component, stamps integrity/crossorigin
+    // onto script/link tags, and bakes the verify manifest into each page.
+    // Keep it AFTER prerender() so it sees the final pages.
+    sri(),
+    // @spark:end
   ],
 });