# Mochi

> Mochi is an SSR-first framework for Svelte 5 on Bun with islands-based selective hydration.

## Docs

- [Welcome](https://mochi.fast/docs/intro/llms.txt): A lightweight, server-first Svelte 5 framework running on Bun that ships client-side JavaScript only for interactive islands.
- [Your first Mochi app](https://mochi.fast/docs/your-first-mochi-app/llms.txt): Build your first page with serverProps, selective hydration, and server islands in four steps.
- [Coming from SvelteKit](https://mochi.fast/docs/coming-from-sveltekit/llms.txt): Map each SvelteKit concept to its Mochi equivalent.
- [Defining routes](https://mochi.fast/docs/defining-routes/llms.txt): Register pages, APIs, WebSockets, SSE endpoints, and file routes with the programmatic routes record.
- [Selective hydration with mochi:hydrate](https://mochi.fast/docs/selective-hydration/llms.txt): Mark components with mochi:hydrate to ship client JavaScript only where you need interactivity.
- [Client-only components with mochi:clientOnly](https://mochi.fast/docs/client-only/llms.txt): Skip SSR and mount a component in the browser with mochi:clientOnly.
- [Lazy hydration with mochi:hydrate:visible](https://mochi.fast/docs/lazy-hydration/llms.txt): Defer island hydration until the component scrolls into view with mochi:hydrate:visible.
- [Server islands with mochi:defer](https://mochi.fast/docs/server-islands/llms.txt): Render components after initial page load by fetching their HTML from the server with mochi:defer.
- [Passing props to islands](https://mochi.fast/docs/island-props/llms.txt): How Mochi serializes props for hydratable islands, the supported types, and reserved names.
- [Hydratable values](https://mochi.fast/docs/hydratable/llms.txt): Serialize computed server values into the page so the client reuses them instead of re-running the work.
- [Server-only imports](https://mochi.fast/docs/server-only-imports/llms.txt): Keep server-only modules like bun:sqlite out of client bundles with the .server.ts convention.
- [Progressively enhancing forms with enhance](https://mochi.fast/docs/progressively-enhancing-forms-with-enhance/llms.txt): Progressively enhance HTML forms to submit over fetch when JavaScript is available.
- [Why Bun?](https://mochi.fast/docs/why-bun/llms.txt): Why Mochi chose Bun as its runtime and which Bun APIs the framework uses.
- [HTTP streaming](https://mochi.fast/docs/http-streaming/llms.txt): Mochi renders each page as one complete document. Use SSE, WebSockets, and server islands for anything that arrives later.
- [Environment constants](https://mochi.fast/docs/environment-constants/llms.txt): Build-time constants for branching on render target (isServer, isBrowser), dev mode (isDev), and the build itself (isBuilding).
- [Request context](https://mochi.fast/docs/request-context/llms.txt): Access the current URL, route params, cookies, and locals from server-side code, plus the isomorphic url export.
- [API routes](https://mochi.fast/docs/api-routes/llms.txt): Register JSON endpoints with Mochi.api() that receive a request event and return a Response.
- [WebSocket routes](https://mochi.fast/docs/websocket-routes/llms.txt): Register WebSocket endpoints with Mochi.ws() and handle upgrade, open, message, close, and drain events.
- [Server-Sent Events](https://mochi.fast/docs/server-sent-events/llms.txt): Push real-time updates to clients over a single HTTP connection with Mochi.sse().
- [Queues](https://mochi.fast/docs/queues/llms.txt): Run background jobs with Mochi.queue(), backed by bun-boss on memory, SQLite, Postgres, or embedded PGlite storage.
- [Email](https://mochi.fast/docs/email/llms.txt): Send transactional email with Mochi.email() over SMTP, a custom send function, or Svelte templates rendered to inlined HTML.
- [Persistence](https://mochi.fast/docs/persistence/llms.txt): Which storage backends each stateful Mochi feature supports — in-memory, file, SQLite, Postgres, or your own store.
- [Middleware (hooks)](https://mochi.fast/docs/middleware/llms.txt): Intercept and transform requests and responses with SvelteKit-style handle functions.
- [Trailing slash](https://mochi.fast/docs/trailing-slash/llms.txt): Enforce a consistent trailing-slash policy across all routes with automatic redirects.
- [Rate limiting](https://mochi.fast/docs/rate-limiting/llms.txt): Per-route and global request rate limiting with memory, SQLite, and Postgres stores.
- [Transforming HTML with transformPage](https://mochi.fast/docs/transform-page/llms.txt): Rewrite rendered HTML before it is sent to the client with the transformPage callback.
- [Error handling](https://mochi.fast/docs/error-handling/llms.txt): Configure a custom error page and control how uncaught errors render to the client.
- [Error boundaries](https://mochi.fast/docs/error-boundaries/llms.txt): Hydratable islands are auto-wrapped in svelte:boundary, so one island failure cannot crash the page.
- [Utility helpers](https://mochi.fast/docs/utility-helpers/llms.txt): Helper functions for building JSON responses, error responses, and form-action results.
- [Cache](https://mochi.fast/docs/cache/llms.txt): Cache server-side data with stale-while-revalidate semantics using MochiCache.
- [Logging](https://mochi.fast/docs/logging/llms.txt): An isomorphic, level-gated logger that works in server, SSR, and client contexts.
- [Request cache](https://mochi.fast/docs/request-cache/llms.txt): Memoize server-side work for the duration of a single request with requestCache and requestMemo.
- [Events](https://mochi.fast/docs/events/llms.txt): Subscribe to framework lifecycle events like requests, WebSocket activity, and builds via a mitt emitter.
- [Images](https://mochi.fast/docs/images/llms.txt): On-the-fly image transforms on Bun.Image via named sizes, with encrypted URLs and a stale-while-revalidate disk cache.
- [View Transitions](https://mochi.fast/docs/view-transitions/llms.txt): Animate full-page navigations with the browser cross-document View Transitions API and zero JavaScript.
- [RawScript](https://mochi.fast/docs/raw-script/llms.txt): Inline the raw contents of a file into the page at SSR time, addressed by a working-directory-relative path.
- [Captcha](https://mochi.fast/docs/captcha/llms.txt): Slide-to-verify captcha with proof-of-work, replay protection, and no third-party service.
- [Custom HTML shell](https://mochi.fast/docs/custom-html-shell/llms.txt): Replace the default HTML wrapper with a custom shell template containing Mochi placeholders.
- [Speculation Rules](https://mochi.fast/docs/speculation-rules/llms.txt): Prefetch and prerender same-site URLs via a typed speculationRules option, injected as a <script type="speculationrules"> tag.
- [CSS imports](https://mochi.fast/docs/css-imports/llms.txt): Import CSS from Svelte, TypeScript, or JavaScript files and have it bundled and injected automatically.
- [MdSvex](https://mochi.fast/docs/mdsvex/llms.txt): Enable Markdown support in Mochi pages with mdsvex and rehype/remark plugins.
- [Serve options](https://mochi.fast/docs/serve-options/llms.txt): Reference for every configuration option on Mochi.serve().
- [Extensions (hooks & filters)](https://mochi.fast/docs/extensions/llms.txt): Observe or transform framework behavior at lifecycle moments with hooks and filters.
- [Svelte config](https://mochi.fast/docs/svelte-config/llms.txt): Customize the Svelte compiler through svelte.config.js with compiler options and framework defaults.
- [Development mode](https://mochi.fast/docs/development-mode/llms.txt): What the development flag enables: live reload, file watcher, route handler HMR, debug bar, and error overlay.
- [Discord](https://mochi.fast/docs/discord/llms.txt): Join the Mochi community on Discord.
- [Debug bar](https://mochi.fast/docs/debug-bar/llms.txt): A floating dev toolbar showing hydration metrics, request data, island breakdown, and bundle stats.
- [Testing](https://mochi.fast/docs/testing/llms.txt): Unit-test with bun:test and run full-app tests in isolated processes with the runTests helper.
- [Tailwind](https://mochi.fast/docs/tailwind/llms.txt): Integrate Tailwind CSS v4 into a Mochi app with the setupTailwind helper.
- [Svelte Shaker optimization](https://mochi.fast/docs/svelte-shaker/llms.txt): Optimize and slim .svelte sources before compilation with the whole-program svelte-shaker optimizer.
- [rsvelte compiler](https://mochi.fast/docs/rsvelte/llms.txt): Swap the JavaScript Svelte compiler for rsvelte, a Rust port built on OXC, to cut compile time.
- [Architecture](https://mochi.fast/docs/architecture/llms.txt): The high-level model behind a Mochi app: server-first rendering, islands, programmatic routes, and the request lifecycle.
- [CLI reference](https://mochi.fast/docs/cli/llms.txt): The mochi-framework command-line tool: build, generate-key, and update-skill.
- [Deployment options](https://mochi.fast/docs/deployment-options/llms.txt): Where to deploy your Mochi app: PaaS, VPS, big cloud, and self-hosted options.
- [Building a Dockerfile](https://mochi.fast/docs/docker/llms.txt): A minimal production Dockerfile template for deploying Mochi apps with Bun.
- [Docs for LLMs](https://mochi.fast/docs/docs-for-llms/llms.txt): A remote MCP server, an agent skill, and an llms.txt index with concatenated bundles for LLM contexts.
- [Demos](https://mochi.fast/docs/demos/llms.txt): Production-style example apps demonstrating Mochi primitives like SSR, hydration, and real-time updates.
- [Mochi vs SvelteKit](https://mochi.fast/docs/mochi-vs-sveltekit/llms.txt): A side-by-side feature comparison of Mochi and SvelteKit, filterable by performance, backend, and frontend.
- [Changelog](https://mochi.fast/docs/changelog/llms.txt): Release notes for every mochi-framework version.

## Examples

- [Hello World](https://mochi.fast/demos/hello-world/llms.txt): How server-side rendering works — a Mochi.page() renders Svelte on the server and ships zero JavaScript.
- [Server Props](https://mochi.fast/demos/server-props/llms.txt): How server props work — pass fresh per-request data into a page via serverProps on Mochi.page().
- [Hydration Modes](https://mochi.fast/demos/hydration/llms.txt): How the hydration modes work — mochi:hydrate, mochi:hydrate:visible, rootMargin tuning, and mochi:defer server islands side by side.
- [Charts with LayerChart](https://mochi.fast/demos/charts/llms.txt): How a third-party Svelte component library works in Mochi — LayerChart server-rendered to plain SVG with zero JavaScript, then the same library as mochi:hydrate and mochi:clientOnly islands.
- [Data Loading](https://mochi.fast/demos/data-loading/llms.txt): How server-side data loading works — fetch on the server, cache with MochiCache, and render at request time.
- [Hydratable](https://mochi.fast/demos/hydratable/llms.txt): How hydratable() works — compute a value once on the server and reuse it on the client instead of re-running async work during hydration.
- [isHydratable()](https://mochi.fast/demos/is-hydratable/llms.txt): How isHydratable() works — detect from any depth whether the current subtree will hydrate, for SSR-only fallbacks without prop forwarding.
- [Cookies](https://mochi.fast/demos/cookies/llms.txt): How cookies work — read and write on the server and the client through one MochiCookieJar API (cookies.get/set/delete).
- [Isomorphic URL](https://mochi.fast/demos/url/llms.txt): How the isomorphic URL helper works — one import that reads the request URL on the server and window.location on the client.
- [Varlock env schemas](https://mochi.fast/demos/varlock/llms.txt): How schema-validated env works — load a typed .env.schema with Varlock and read coerced, expanded, redacted config through the ENV proxy on every SSR render.
- [View Transitions](https://mochi.fast/demos/view-transitions/llms.txt): How view transitions work — drop <ViewTransitions /> into a layout to animate full-page navigations with zero JavaScript.
- [Custom Transitions](https://mochi.fast/demos/custom-transitions/llms.txt): How custom view transitions work — supply your own @keyframes to <ViewTransitions /> via custom={{ in, out }}.
- [Cache Events](https://mochi.fast/demos/cache-events/llms.txt): How cache events work — subscribe to MochiCache lifecycle events (hit, miss, set, evict) through mochiEvents for observability.
- [Request Cache](https://mochi.fast/demos/request-cache/llms.txt): How the request cache works — requestMemo and requestCache run an expensive computation once per request no matter how many components call it, then discard it at the request boundary.
- [Image: Component](https://mochi.fast/demos/image/llms.txt): How the <Image> component works — named sizes, ThumbHash blur-up placeholders, and encrypted deferred URLs whose transforms run lazily on the endpoint.
- [Image: Invalidation](https://mochi.fast/demos/image-invalidation/llms.txt): How image invalidation works — invalidateImage() hard-evicts the shared original so every named size re-fetches in lockstep.
- [Image: Named sizes](https://mochi.fast/demos/image-pipeline/llms.txt): How the image transform pipeline works — declare resize / rotate / flip / modulate / format as named sizes; getImageUrl mints a deferred URL, getImage runs one inline.
- [Image: Events](https://mochi.fast/demos/image-events/llms.txt): How image events work — subscribe to image:store / image:delete on mochiEvents to mirror the <Image> cache to durable storage like S3.
- [Request ID](https://mochi.fast/demos/request-id/llms.txt): How request IDs work — every request gets a UUID v7 on getRequestContext().requestId that rides every lifecycle event for correlation.
- [Cookie Vary Test](https://mochi.fast/cookie-vary-test/llms.txt): How cookie-partitioned caching works — a page that sets Vary: Cookie so responses key on cookies.
- [Real-time Chat](https://mochi.fast/demos/chat/llms.txt): How WebSocket routes work — a hydrated island over Mochi.ws() with pub/sub broadcast and in-memory history.
- [API Endpoints](https://mochi.fast/demos/api/llms.txt): How API routes work — define JSON endpoints with Mochi.api(), tested live against the running server.
- [Rate Limiting](https://mochi.fast/demos/rate-limit/llms.txt): How rate limiting works — a rateLimit config on the route caps requests per IP per minute and serves the 429 error page past the limit.
- [File Routes](https://mochi.fast/demos/file/llms.txt): How file routes work — serve a file from disk with Mochi.file(), as a static path or a per-request resolver.
- [Shared State](https://mochi.fast/demos/shared-state/llms.txt): How shared state across islands works — two separate islands driving the same reactive $state.
- [Real-time Streams](https://mochi.fast/demos/streams/llms.txt): How server-sent events and WebSocket streaming work — live SSE and WebSocket clocks, lazily hydrated via mochi:hydrate:visible.
- [Background jobs with queues](https://mochi.fast/demos/queue/llms.txt): How background job queues work — offload work to a Mochi.queue() with an embedded worker, no Redis.
- [Server Islands](https://mochi.fast/demos/server-island/llms.txt): How server islands work — components marked mochi:defer render server-side on demand after the initial page is delivered.
- [Crossing the server-client boundary with props](https://mochi.fast/demos/island-props/llms.txt): How props cross the server-client boundary — Date, Map, Set, BigInt, URL, typed arrays, and even cyclic refs survive devalue's round-trip into a hydrated island.
- [Client-only Islands](https://mochi.fast/demos/client-only/llms.txt): How client-only islands work — components marked mochi:clientOnly skip SSR and mount in the browser, with a fallback snippet until then.
- [Lazy Islands](https://mochi.fast/demos/lazy/llms.txt): How lazy hydration works — islands marked mochi:hydrate:visible hydrate and load their CSS only when scrolled into view.
- [Lazy Server Islands](https://mochi.fast/demos/lazy-server-island/llms.txt): How lazy server islands work — server islands marked mochi:defer:visible only fetch when the wrapper scrolls into view.
- [Font loading](https://mochi.fast/demos/font-loading/llms.txt): How font loading works — ship fonts via @fontsource packages or standalone .woff2 files, automatically bundled and linked from the page head.
- [MdSvex](https://mochi.fast/demos/mdsvex/llms.txt): How mdsvex works — a .md file compiled through mdsvex and rendered as a Svelte component, embedded <script> and all.
- [Portable Text](https://mochi.fast/demos/portable-text/llms.txt): How Portable Text rendering works — @portabletext/svelte maps a JSON block array onto your own Svelte components for types, marks, block styles and lists.
- [Nested Components](https://mochi.fast/demos/nested-components/llms.txt): How whole-subtree hydration works — a five-level recursive tree where hydrating the root carries the entire subtree in one island.
- [Nested Islands](https://mochi.fast/demos/nested-islands/llms.txt): How nested islands work — a mochi:defer server island wrapping mochi:hydrate components, and server islands nesting more server islands.
- [Nested Island Max Depth](https://mochi.fast/demos/island-depth/llms.txt): How deeply nested server islands work — a four-level mochi:defer chain where each level fetches the next on demand and the prebuild precompiles the whole chain.
- [Shared Props](https://mochi.fast/demos/prop-dedup/llms.txt): How island prop deduplication works — nine islands share three unique payloads, each serialized once and referenced via props-ref.
- [Unique IDs](https://mochi.fast/demos/props-id/llms.txt): How stable island IDs work — Svelte's native $props.id() gives SSR-consistent, per-instance ids, namespaced inside server islands.
- [Form Actions](https://mochi.fast/demos/login/llms.txt): How form actions work — a form rendered twice, as a plain HTML POST and intercepted with {@attach enhance(...)}.
- [Send Email](https://mochi.fast/demos/email/llms.txt): How sending email works — dispatch through Mochi.email() and read it back in the /_mochi/email dev outbox.
- [Using form return data](https://mochi.fast/demos/form-return-data/llms.txt): How form action return data works — an action returns success({...}); {@attach enhance(...)} updates the UI in place, plain HTML re-renders.
- [Form Errors](https://mochi.fast/demos/form-errors/llms.txt): How form action errors work — a thrown action error shows inline via {@attach enhance(...)}, or as the Mochi error page on a plain submit.
- [Form Redirects](https://mochi.fast/demos/form-redirects/llms.txt): How form action redirects work — redirect(303, …) is intercepted as a JSON envelope by {@attach enhance(...)} or followed natively by the browser.
- [File Uploads via form actions](https://mochi.fast/demos/file-upload/llms.txt): How file uploads through form actions work — multipart/form-data validated with fail() and success(), shown enhanced and plain.
- [Reloading associated form data](https://mochi.fast/demos/reload-form-data/llms.txt): How reloading associated data works — after a successful submit, refetch the related list inside enhance(), or rely on the post-POST re-render.
- [Captcha](https://mochi.fast/demos/captcha/llms.txt): How the captcha works — slide-to-verify backed by a hash chain and proof-of-work, with no third party and no tracking.
- [Captcha Styling](https://mochi.fast/demos/captcha-styling/llms.txt): How captcha theming works — the same captcha four ways, every colour a CSS custom property with a built-in fallback.
- [Cancelling form submissions](https://mochi.fast/demos/form-cancel/llms.txt): How cancelling form submissions works — cancel() stops the fetch before it fires; controller.abort() stops one mid-flight.
- [Error Handling](https://mochi.fast/demos/error/llms.txt): How error handling works — catch render errors and unmatched routes via Mochi.serve()'s errorPage option and the handleError hook.
- [Error Boundaries](https://mochi.fast/demos/error-boundaries/llms.txt): How error boundaries work — contain island failures with <svelte:boundary> so one broken component doesn't crash the page.
- [HTML Entities in Props](https://mochi.fast/demos/entity-props/llms.txt): How HTML entities in island props work — an entity in a static prop (label="Tom &amp; Jerry") decodes identically on the server and after hydration.
- [Mode Watcher](https://mochi.fast/demos/mode-watcher/llms.txt): Light/dark mode in an island — mode-watcher's <ModeWatcher />, toggleMode/setMode, and the mode / userPrefersMode / systemPrefersMode runes driving the global <html> theme.
- [Runed Utilities](https://mochi.fast/demos/runed/llms.txt): How third-party Svelte 5 libraries run in islands — Runed's reactive utilities (Debounced, StateHistory, PersistedState, PressedKeys, AnimationFrames, FiniteStateMachine, resource…) hydrated inside Mochi.
- [Tables with TanStack Table](https://mochi.fast/demos/tanstack-table/llms.txt): How a headless table library works in Mochi — TanStack Table server-rendered to a read-only table with zero JavaScript, then a mochi:hydrate island for interactive sorting.

## Blog

- [Mochi 0.9.0](https://mochi.fast/blog/mochi-0-9-0/llms.txt): 2026-07-28 — The rsvelte compiler backend, per-request caching, relocatable build output, and precompiled email templates — 30 commits since 0.8.0.
- [Mochi 0.8.0](https://mochi.fast/blog/mochi-0-8-0/llms.txt): 2026-07-21 — Queues, transactional email, image transforms, captcha and rate limiting — 93 commits since 0.7.0.
- [Mochi on This Week in Svelte](https://mochi.fast/blog/this-week-in-svelte/llms.txt): 2026-07-20 — A live walkthrough of Mochi with Paolo Ricciuti on This Week in Svelte.
- [Hello World](https://mochi.fast/blog/hello-world/llms.txt): 2026-07-14 — Introducing the Mochi blog.

## Optional

- [All docs concatenated](https://mochi.fast/llms-recommended.txt): The full documentation in reading order.
- [Docs + every demo's source](https://mochi.fast/llms-full.txt): Everything, for maximum context.