create-spark-html-app 0.6.0 → 0.7.1

package/README.md

@@ -25,14 +25,59 @@ 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.
 
+## 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.
+
+| Package | What it does |
+|---|---|
+| [`spark-html`](https://www.npmjs.com/package/spark-html) | The runtime — components, reactivity, stores, forms, scoped styles. 13 kB gzip, 0 deps. |
+| [`spark-html-router`](https://www.npmjs.com/package/spark-html-router) | `<template route>` routing — nested routes/layouts, `route.query`, active links. |
+| [`spark-html-theme`](https://www.npmjs.com/package/spark-html-theme) | Dark/light/system theming in one line — persisted, no flash. |
+| [`spark-html-head`](https://www.npmjs.com/package/spark-html-head) | Reactive `<title>`/`<meta>` per route + a `head` store. |
+| [`spark-html-motion`](https://www.npmjs.com/package/spark-html-motion) | Enter/leave transitions on if/each blocks — `transition="fade|slide|scale"`. |
+| [`spark-html-devtools`](https://www.npmjs.com/package/spark-html-devtools) | In-page devtools — live stores, component tree, patch activity. |
+| [`spark-html-query`](https://www.npmjs.com/package/spark-html-query) | Declarative async data — a self-fetching store (`loading`/`error`/`data`/`refetch`). |
+| [`spark-html-persist`](https://www.npmjs.com/package/spark-html-persist) | Persist stores to localStorage/sessionStorage in one line. |
+| [`spark-html-websocket`](https://www.npmjs.com/package/spark-html-websocket) | A WebSocket as a reactive store — auto-reconnect, JSON, `send()`. |
+| [`spark-prerender`](https://www.npmjs.com/package/spark-prerender) | Build-time SEO prerender + sitemap/robots — no SSR server. |
+| [`spark-html-image`](https://www.npmjs.com/package/spark-html-image) | Build-time image optimization — webp/avif + responsive `srcset`, zero config. |
+| [`spark-html-font`](https://www.npmjs.com/package/spark-html-font) | Font loading optimizer — preload + size-adjusted fallbacks, no FOUT. |
+| [`spark-html-manifest`](https://www.npmjs.com/package/spark-html-manifest) | PWA manifest + icons + head tags (and optional service worker) from one config. |
+| [`spark-html-offline`](https://www.npmjs.com/package/spark-html-offline) | Offline URL imports — a service worker that caches CDN components. |
+| [`spark-html-sri`](https://www.npmjs.com/package/spark-html-sri) | Subresource Integrity — hash + verify assets and remote components. |
+| [`create-spark-html-app`](https://www.npmjs.com/package/create-spark-html-app) | Scaffold a Vite + spark-html app in one command. |
+| [`prettier-plugin-spark`](https://www.npmjs.com/package/prettier-plugin-spark) | Prettier for components — formats `<script>`/`<style>`, markup stays byte-for-byte. |
+| [`spark-html-language-server`](https://www.npmjs.com/package/spark-html-language-server) | LSP — diagnostics, go-to-definition, prop autocomplete, hover docs. |
+
 ## License
 
 MIT

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.6.0",
+  "version": "0.7.1",
   "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/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/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,8 +18,8 @@ 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.
@@ -19,6 +28,28 @@ export default defineConfig({
   },
   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
   ],
 });