@solcreek/svelte-adapter

SvelteKit deployment adapter for @solcreek/creekd self-host. Produces a runnable HTTP server entry + a .creek-creekd/manifest.json describing the supervised process, so creekctl up --from .creek-creekd/manifest.json knows exactly what to spawn.

Pairs creekd's neutral process supervisor (cgroups, namespaces, dispatch, health probes) with SvelteKit-shaped defaults: prerendered fast-path, hashed-asset immutable caching, X-Forwarded-* aware URL rebuilding, sveltekit:shutdown graceful drain.

@sveltejs/adapter-node    /bench/slow      ⏤  191 req/s  ·  52 ms p50
@solcreek/svelte-adapter  /bench/slow      ⏤  191 req/s  ·  52 ms p50   (zero overhead)
@solcreek/svelte-adapter  /bench/cached    ⏤  11,680 req/s · 0.67 ms p50  ← platform.cache

pnpm bench reproduces these numbers on your machine. The cached path uses event.platform.cache (L1 LRU + L2 filesystem, survives restart, tag invalidation) — see Benchmark and platform.cache.

Status

Pre-1.0, targets SvelteKit ≥ 2.0. The adapter is feature-complete vs @sveltejs/adapter-node (same env-var surface, same sveltekit:shutdown contract, same node_modules-on-target deployment model) and adds platform.cache as its differentiator. Self-host, Bun runtime, and creekctl integration are first-class.

Install

pnpm add -D @solcreek/svelte-adapter

Usage

// svelte.config.js
import adapter from "@solcreek/svelte-adapter";

export default {
  kit: {
    adapter: adapter({
      runtime: "bun",   // default; "node" is the safe fallback
      port: 3000,
      // healthCheckPath: "/_creek/health",   // default
      // precompress: true,                   // default
      // env: { FEATURE_X: "1" },             // additive over NODE_ENV=production
    }),
  },
};

After pnpm build:

• build/index.js — the runtime entry (Node or Bun)
• build/server/, build/client/, build/prerendered/ — SvelteKit output
• .creek-creekd/manifest.json — what creekd reads to spawn the process

Spawn under creekd:

creekctl up --from .creek-creekd/manifest.json

Options

platform.cache — persistent KV for SvelteKit (the differentiator vs adapter-node)

SvelteKit doesn't ship a first-class ISR or cache-handler primitive — there's no equivalent of Next.js's cacheHandler. This adapter exposes a small persistent cache on event.platform.cache so user code can do tag-invalidated, restart-surviving caching without bolting on Redis just to self-host.

// src/routes/+page.server.ts
export async function load({ platform }) {
  return {
    feed: await platform.cache.cached(
      "homepage-feed:v1",
      { revalidate: 60, tags: ["feed"] },
      async () => {
        // expensive query — runs once per minute (or after invalidateTag)
        return await db.feed.recent();
      },
    ),
  };
}

// src/routes/api/publish/+server.ts
export async function POST({ platform, request }) {
  await db.posts.insert(await request.json());
  await platform.cache.invalidateTag("feed");
  return new Response(null, { status: 204 });
}

Implementation:

• L1: in-process LRU (insertion-order Map; default 2048 entries)
• L2: pluggable driver. bun-sqlite on Bun (single cache.sqlite with WAL); fs on Node (one JSON per entry under $CREEK_SVELTE_CACHE_DIR/entries/<hash[0:2]>/<hash>.json, atomic via tmp+rename). auto (default) picks the right one at startup.
• Tags: per-tag invalidation sentinel { invalidatedAt }; entries are stale if any of their tags was invalidated after entry.createdAt. Stored as a tags row in sqlite, as tags/<safe>.json in fs.
• SWR: cached() returns stale data while a background loader refreshes; coalesces concurrent misses for the same key
• Dev parity: adapter.emulate() provides the same cache in vite dev and prerender via event.platform.cache — no if (import.meta.env.DEV) branches needed
• Graceful shutdown: cache is closed (in-flight writes flushed; sqlite WAL checkpointed) after sveltekit:shutdown listeners run

L2 driver microbench (1000 set + 1000 cold-L2 get, Bun 1.3, M-series macOS):

~6× write throughput, ~7× read throughput. The fs driver isn't slow in absolute terms — sqlite just avoids the per-entry mkdir/tmp/rename syscall trio and WAL gives durable writes without per-write fsync. The fs driver remains the only choice on Node.

Cache env vars

App.Platform typing

To get autocomplete on event.platform.cache, declare it in your project's src/app.d.ts:

import type { CreekdSvelteCache } from "@solcreek/svelte-adapter/runtime";

declare global {
  namespace App {
    interface Platform {
      cache: CreekdSvelteCache;
    }
  }
}
export {};

Runtime environment variables

The generated entry honours the same env vars as @sveltejs/adapter-node, so existing Svelte deployment knowledge transfers directly:

Graceful shutdown

The entry emits the sveltekit:shutdown event on SIGINT / SIGTERM with the signal name as the reason; listeners may return promises and they are all awaited before the socket is closed. Use this to close DB pools, flush queues, etc.

// instrumentation.server.ts (or any module loaded at startup)
process.on("sveltekit:shutdown", async (reason) => {
  await db.end();
});

SPA / catch-all fallback

For SPA-mode apps (everything client-rendered) or for a styled custom 404 page, pass a fallback filename. The adapter calls builder.generateFallback() to write the SvelteKit root layout as a static HTML shell into the prerendered output, and the server entry serves that file on any SSR 404:

// svelte.config.js
import adapter from "@solcreek/svelte-adapter";
export default {
  kit: { adapter: adapter({ fallback: "200.html" }) },
};

Status code follows the filename: 404.html → 404, anything else (200.html, index.html, …) → 200. Prerendered hits and successful SSR responses still win — fallback only fires when SSR returns 404.

Instrumentation (SvelteKit 2.31+)

If you provide src/instrumentation.server.ts, this adapter wraps the generated entry so the instrumentation module loads before any application code — required for OpenTelemetry auto-instrumentation, logger init, DB pool warm-up, etc. No configuration needed; enable the kit feature in svelte.config.js:

// svelte.config.js
export default {
  kit: {
    experimental: { instrumentation: { server: true } },
    adapter: adapter(),
  },
};

// src/instrumentation.server.ts
import { NodeSDK } from "@opentelemetry/sdk-node";
import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";

const sdk = new NodeSDK({ instrumentations: [getNodeAutoInstrumentations()] });
sdk.start();

Caveats inherited from kit's builder.instrument(): "live exports" do not work (none in this adapter's entry), and OTel auto-instrumentation needs top-level-await runtime support (Node 14.8+ / Bun — always satisfied here).

Benchmark vs @sveltejs/adapter-node

Same minimal SvelteKit fixture, same Node version, same hardware, 2000 requests at concurrency 10. /bench/slow simulates a 50 ms backend dependency; /bench/cached wraps it in platform.cache.cached.

Two takeaways:

1. No overhead vs adapter-node on the uncached path — identical throughput and latency, so adopting this adapter doesn't make anything slower.
2. 78× faster p50 and 61× higher throughput on the cached path. The same backend dependency, the same SvelteKit Server, just one platform.cache.cached(...) call.

Run the benchmark yourself: pnpm bench (uses the fixture at test/fixtures/real-sveltekit/, takes ~30 s).

Deployment

Default mode (bundle: false) ships build/ + node_modules to the target, exactly like @sveltejs/adapter-node:

git pull
pnpm install --prod
pnpm build
creekctl up --from .creek-creekd/manifest.json

Bundling via esbuild

Opt in with adapter({ bundle: "esbuild" }). The adapter inlines @sveltejs/kit/node + polyfills + cache handler into a single build/index.js so the target needs no node_modules:

// svelte.config.js
import adapter from "@solcreek/svelte-adapter";
export default {
  kit: { adapter: adapter({ bundle: "esbuild" }) },
};

Numbers from test/fixtures/real-sveltekit/. Inline source maps are included so production stack traces remain readable.

What stays external:

• ./server/* — kit's Server dynamically imports route modules relative to its own location, so the server bundle must stay on disk under build/server/. Inlining it would break route loading at runtime.
• bun:sqlite — Bun built-in, resolved at runtime (no npm package).
• node:* — Node built-ins.

What's not handled automatically: native modules outside the kit server bundle (better-sqlite3, sharp, @node-rs/*, prebuilt .node binaries). If your app needs these, stick with bundle: false for now — extension of the externals list is a later iteration.

Comparison with @sveltejs/adapter-node

On the apples-to-apples path (no caching), throughput and latency are identical — adopting this adapter doesn't make anything slower. See Benchmark for the numbers and methodology.

License

Apache-2.0