React SPA

Status: ✅ Supported. @ditherkit/react works in any React app without configuration. A dedicated example app is backlogged (apps/example-vite-react) but the quick start below is complete.

If you're on a plain React SPA — Vite, Rsbuild, or anything non-Next.js — you just need @ditherkit/react. No route handlers, no server setup, no Sharp. Everything happens in the browser.

What works

<DitheredImage /> — the full React component, unchanged.
Web Worker bundling — Vite and Rsbuild pick up the new URL('./dither.worker.mjs', import.meta.url) pattern automatically.
All algorithms and controls — Floyd-Steinberg, Atkinson, Threshold, custom palettes, brightness, contrast.
Shared worker across instances — one Web Worker per page, multiplexed across every <DitheredImage /> you render.
Safari fallback — ctx.filter isn't supported in Safari's OffscreenCanvas; the component detects Safari and uses a pure-JS brightness/contrast path automatically.

Quick start (Vite)

pnpm add @ditherkit/react

// src/App.tsx
import { DitheredImage } from '@ditherkit/react'

export function App() {
  return (
    <DitheredImage
      src="/portrait.jpg"
      alt="A dithered portrait"
      width={400}
      height={600}
      algorithm="Atkinson"
    />
  )
}

That's it. No vite.config.ts changes needed — Vite's native Web Worker support handles the worker URL pattern out of the box.

Quick start (Rsbuild / Rspack)

Same as Vite. Install, import, use. Rspack understands the Web Worker URL pattern natively.

pnpm add @ditherkit/react

Why no server-rendered option?

React SPAs don't have a server that renders images on demand, so there's nothing for @ditherkit/next to plug into. If you want cached server-rendered dithered images in a React SPA, you have two options:

Pre-render at build time. Use @ditherkit/core + sharp in a prebuild script to process your source images into dithered outputs that ship with your static site.
Add a small backend. A Cloudflare Worker, a Vercel Function, a Netlify Function, or a small Express server calling ditherImage() from @ditherkit/next/server. Your React app fetches from it like any other API.

Neither is as smooth as the @ditherkit/next path in a Next.js app, but both are reasonable. The build-time option is best if your source images don't change often; the small-backend option is best if they do.

What doesn't work (yet)

Create React App (CRA). CRA is deprecated by Meta and the Web Worker URL pattern requires Webpack 5 config changes that CRA doesn't expose. Migrate to Vite.
Server-side pre-rendering inside a Vite app. Vite SSR is a different beast than Next.js SSR and @ditherkit/next is Next.js-specific. Use @ditherkit/core directly in your Vite SSR handler.

Example app

A dedicated Vite + React example app is in progress. Until it lands, the quick start above is the complete reference — there's nothing extra you need.