🍡 mochi

SSR framework for Svelte 5 + Bun with islands-based selective hydration

On this page

Production builds

mochi-framework build writes a self-contained build to .mochi/ (see the CLI reference). This page covers what that build gives you once it is deployed: it relocates cleanly from where you built it to where you run it, it can be hosted under a sub-path, and its image cache can survive container restarts. For where to run it, see Deployment options; to containerize it, see Building a Dockerfile.

Relocatable builds

A manifest holds no absolute paths — artifacts are written relative to the out-dir, sources relative to the project root — so you can build in one place and run in another. Build in a CI stage, copy .mochi/ into the final image, and point the runtime at wherever it landed:

Mochi.serve({ outDir: './.mochi' }); // default — or wherever you copied it

Paths resolve against the manifest’s own directory, so pointing manifest at a relocated build works on its own:

Mochi.serve({ manifest: '/srv/app/build/manifest.json' });

Sub-path and static hosting

Mochi writes absolute URLs for everything it owns: /_mochi/client/…, /_mochi/css/…, the island component-url, and the import specifiers inside the client chunks. To host under a sub-path such as https://example.com/my-app/, bake the prefix in at build time:

mochi-framework build --asset-prefix /my-app/_mochi

The value lands in manifest.json and every emitted URL carries it. Mochi.serve({ assetPrefix }) sets the same thing for on-demand compilation, but once a manifest exists its value wins and a differing serve() value only logs a warning.

The same prefix is what makes a hand-rolled static export work: copy .mochi/svelte-client to <host>/my-app/_mochi/client and .mochi/svelte-css to <host>/my-app/_mochi/css, save each prerendered page, and nothing needs rewriting.

Rewriting URLs yourself

Since: 0.10.0 (not released yet): Before 0.10.0 a relative component-url resolved against the island loader module (/_mochi/client/), not the page.

If you post-process the HTML into page-relative URLs instead, treat component-url like any other attribute: it resolves against the page, so ../_mochi/client/… on /my-app/writing/ loads from /my-app/_mochi/client/, the same place a <link href="../_mochi/css/…"> on that page does.

Persistent image cache

Mochi’s image cache is written to disk under cacheDir (default ./.mochi/image-cache). In a container that directory is recreated on every restart, so each redeploy starts with a cold cache and re-fetches and re-transforms every image. To keep the transformed bytes across restarts, point cacheDir at a dedicated path and mount a volume there:

Mochi.serve({
  image: { cacheDir: process.env.MOCHI_IMAGE_CACHE_DIR /* , sizes: … */ },
});
services:
  site:
    image: your-app
    environment:
      MOCHI_IMAGE_CACHE_DIR: /data/image-cache
    volumes:
      - image-cache:/data/image-cache

volumes:
  image-cache:

A plain docker run -v image-cache:/data/image-cache your-app mounts the same volume. Keep the mount off ./.mochi — its build cache is rebuilt on every boot and must not persist. If the container runs as a non-root user, pre-create the directory owned by that user in your Dockerfile so the mounted volume is writable.

JavaScript minifier

Since: 0.10.0 (not released yet): The minifier option was added in 0.10.0. Earlier versions always use Bun's minifier.

Client JavaScript is minified by Bun’s bundler. Set minifier: 'oxc' to run a second oxc pass over the chunks Bun emitted, which takes roughly another 3–4% off the bundle.

Install oxc-minify and set the option:

bun add -d oxc-minify
// src/index.ts
await Mochi.serve({
  minifier: 'oxc',
  routes: {
    '/': Mochi.page('./src/Home.svelte'),
  },
});

mochi-framework build reads the option from your entry. Override it per build with --minifier <bun|oxc>, or for any process — including the dev server, which has no build step — with MOCHI_MINIFIER:

mochi-framework build --minifier oxc
MOCHI_MINIFIER=oxc bun run dev

Precedence is --minifier, then MOCHI_MINIFIER, then the Mochi.serve() option, then 'bun'. An unknown value from any of them is an error, even one a higher source overrides.

The pass covers the hydration bundle, the debug-bar bundle and the inline web-component scripts. CSS, static assets and the SSR build are untouched. Bun’s own minifier keeps running first — it mangles identifiers across the whole split graph, which oxc cannot redo one chunk at a time — so oxc is purely additive.

With 'oxc', every chunk name carries a tag derived from the installed oxc-minify version and its options — PageA-k3v9x2mq-o9f8e7d6c.js rather than PageA-a1b2c3d4.js. Chunks are served immutable, so switching minifier or upgrading oxc-minify changes every URL and no browser or CDN keeps stale bytes. With 'bun' the names are unchanged. Source maps are not supported with 'oxc'; a build that emits one fails.

Legal (/*!, @license) comments are stripped under 'oxc', while Bun’s minifier keeps them. If your app must ship third-party licence notices, provide them separately, for example on a licences page or in a file. Otherwise behaviour is pinned to match the Bun pass: debugger and console.* are kept, property reads are always treated as side-effecting so a bare obj.prop dependency read survives, and nothing is downlevelled. The two inline classic scripts are built as IIFEs and minified in script mode, the goal the browser parses them with.

One difference from Bun remains: oxc deletes a bare call to a coercing built-in such as String(x), parseInt(x), isNaN(x), Math.abs(x) or encodeURIComponent(x). Inside an $effect, $effect.pre or $derived.by that call can be the only read of a $state proxy, so the effect stops re-running. Mochi warns at compile time, with the file, line and a replacement:

<script>
  let filters = $state(['red']);
  let page = $state(1);

  $effect(() => {
    String(filters); // ❌ removed by 'oxc'
    `${filters}`; // ✅ same reads, survives
    page = 1;
  });
</script>

JSON.stringify(filters), $state.snapshot(filters) and a property read such as filters.length survive too. For a numeric coercion (isNaN, Math.*) the warning suggests Number(x).