⚡ spark-html-image

Build-time image optimization for spark-html sites — a spark-html-bun pipeline step that converts your <img> references to webp/avif with a responsive srcset, zero config. No more hand-written scripts/optimize-images.js wired into the build command.

// spark.config.js
import prerender from 'spark-prerender/bun';
import image from 'spark-html-image/bun';

export default {
  pipeline: [prerender(), image()],
};

That's it. After the build, every local .png/.jpg referenced by an <img> in the output — pages and component .html fragments — is:

• converted to webp at several widths (never upscaled past the original),
• rewritten with srcset + sizes (the original file stays as the src fallback),
• given width/height (no layout shift) and loading="lazy" + decoding="async" when absent.

<img src="/img/hero.png" alt="hero">
<!-- becomes -->
<img src="/img/hero.png" alt="hero"
     srcset="/img/hero-640.webp 640w, /img/hero-960.webp 960w, /img/hero.webp 1600w"
     sizes="100vw" width="1600" height="900" loading="lazy" decoding="async">

External URLs, SVGs, and any <img> that already has a srcset (or sits in a <picture>) are left alone — the author knows best.

Install

bun add -d spark-html-image

Options

| Option | Default | Meaning | |--------|---------|---------| | widths | [640, 960, 1280, 1920] | srcset widths, capped at each image's intrinsic width. | | formats | ['webp'] | 'webp' and/or 'avif'; order = <source> order in picture mode. | | quality | 80 | Encoder quality. | | sizes | '100vw' | Written alongside srcset when the img has no sizes. | | picture | false | Wrap in <picture> with one <source> per format (use with avif). | | lazy | true | Add loading="lazy" + decoding="async" when absent. |

image({ formats: ['avif', 'webp'], picture: true, quality: 75 })

It runs in closeBundle (order post), after spark-prerender has written its per-route HTML — so prerendered pages are optimized too. Conversion uses sharp.

The Spark family

Small, single-purpose packages that share one philosophy: no compiler, no 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 | |---|---| | spark-html | The runtime — components, reactivity, stores, forms, scoped styles. ~14.4 kB gzip, 0 deps. | | spark-html-bun | Dev server, bundler & preview on Bun — scoped HMR, no-build dev, post-build pipeline. | | spark-html-router | <template route> routing — nested routes/layouts, route.query, active links. | | spark-html-theme | Dark/light/system theming in one line — persisted, no flash. | | spark-html-head | Reactive <title>/<meta> per route + a head store. | | spark-html-motion | Enter/leave transitions on if/each blocks — transition="fade|slide|scale". | | spark-html-devtools | In-page devtools — live stores, component tree, patch activity. | | spark-html-query | Declarative async data — a self-fetching store (loading/error/data/refetch). | | spark-html-persist | Persist stores to localStorage/sessionStorage in one line. | | spark-html-websocket | A WebSocket as a reactive store — auto-reconnect, JSON, send(). | | spark-prerender | Build-time SEO prerender + sitemap/robots — no SSR server. | | spark-ssr | Full-stack SSR on Bun — the template is the backend: inferred DB, REST CRUD, auth, live updates. Precompiled + response-cached: fast by default. | | spark-html-image | Build-time image optimization — webp/avif + responsive srcset, zero config. | | spark-html-font | Font loading optimizer — preload + size-adjusted fallbacks, no FOUT. | | spark-html-manifest | PWA manifest + icons + head tags (and optional service worker) from one config. | | spark-html-offline | Offline URL imports — a service worker that caches CDN components. | | spark-html-sri | Subresource Integrity — hash + verify assets and remote components. | | create-spark-html-app | Scaffold a spark-html app in one command. | | prettier-plugin-spark | Prettier for components — formats <script>/<style>, markup stays byte-for-byte. | | spark-html-language-server | LSP — diagnostics, go-to-definition, prop autocomplete, hover docs. |