sailfork / t3code-github / .repos/ alchemy-effect/ website/ src/ content/ docs/ cloudflare/ frontend/ sveltekit.mdx

import PackageManagers from "../../../../components/PackageManagers.astro";
export const devDeps = "@alchemy.run/frontend-frameworks";

Cloudflare.Website.SvelteKit deploys a SvelteKit app as a Cloudflare Worker. It builds the app with SvelteKit's own Vite pipeline and a wrangler-free in-memory Cloudflare adapter, then re-bundles the server output for workerd. Client assets and prerendered pages deploy as Worker static assets; dynamic routes are served by the generated Worker. Your vite.config.ts loads natively; there is no svelte.config.js to write (kit v3 dropped it), no @sveltejs/adapter-cloudflare to install, and no Wrangler file.

Install

The build integration is not bundled with alchemy. Install @alchemy.run/frontend-frameworks; the resource loads its /sveltekit export from your project at deploy time. It is only used at build time, so a dev dependency is enough:

Configure SvelteKit

Your project's vite.config.ts loads natively — your Vite plugins and the kit options in your sveltekit(...) call all apply as usual. Alchemy injects its own wrangler-free Cloudflare adapter (replacing any adapter you declare, with a warning), so a fresh SvelteKit project deploys as-is. Deploy-specific kit overrides can also be passed via the kit prop, which merges over your sveltekit(...) options — see Kit options and 404 handling below. A project without a vite.config.* works too: the resource falls back to a fully programmatic build.

Declare the Website

Declare the site as a module-level const (rather than inline in the Stack) and derive the typed shape of its bindings from it:

// alchemy.run.ts
import * as Cloudflare from "@alchemy.run/cloudflare";

export const Website = Cloudflare.Website.SvelteKit("Website");

export type WebsiteEnv = Cloudflare.InferEnv<typeof Website>;

WebsiteEnv is the typed shape of the Worker's bindings, derived from the class — you'll import it into your SvelteKit code in Read bindings in server code.

Add it to the Stack

Yield the class from your Stack and return its URL:

// alchemy.run.ts
import * as Alchemy from "alchemy";
import * as Effect from "effect/Effect";

export default Alchemy.Stack(
  "MySvelteKitSite",
  {
    providers: Cloudflare.providers(),
    state: Cloudflare.state(),
  },
  Effect.gen(function* () {
    const site = yield* Website;
    return { url: site.url };
  }),
);

SvelteKit's server code is built for Node, so the nodejs_compat compatibility flag is added automatically — you don't need to pass it.

See examples/cloudflare-website-sveltekit for the checked-in example.

Add bindings

The resource returns a plain Worker, so env accepts the full binding vocabulary — KV namespaces, R2 buckets, Durable Objects, secrets:

// alchemy.run.ts
+import * as Config from "effect/Config";

+export const Cache = Cloudflare.KV.Namespace("Cache");

export const Website = Cloudflare.Website.SvelteKit("Website", {
+  env: {
+    CACHE: Cache,
+    API_KEY: Config.Redacted("API_KEY"),
+  },
});

Cache is a description, not a deploy — Alchemy provisions the real namespace because the Website binds it. Config.Redacted reads API_KEY from your environment at deploy time and binds it as a Worker secret — see Secrets & env.

Read bindings in server code

Server routes read bindings through SvelteKit's platform.env. Type it once by augmenting App.Platform with the inferred env type:

// src/app.d.ts
import type { WebsiteEnv } from "../alchemy.run.ts";

declare global {
  namespace App {
    interface Platform {
      env: WebsiteEnv;
    }
  }
}

export {};

Every server route now gets fully typed bindings:

// src/routes/+page.server.ts
export const load = async ({ platform }) => {
  const cached = await platform?.env?.CACHE.get("greeting");
  return { greeting: cached ?? "hello" };
};

platform.env.CACHE is typed as a KV namespace and platform.env.API_KEY as a string — renaming a binding in alchemy.run.ts is a type error in your routes.

Kit options and 404 handling

Since kit v3 there is no svelte.config.js — kit options live in the sveltekit(...) call in your vite.config.ts, which loads natively:

// vite.config.ts
import { sveltekit } from "@sveltejs/kit/vite";
import tailwindcss from "@tailwindcss/vite";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [
    tailwindcss(),
    sveltekit({
      prerender: { handleHttpError: "warn" },
    }),
  ],
});

The kit prop is the deploy-time override bag: JSON-serializable kit config merged over your own sveltekit(...) options (the prop wins). Use it for per-stage values or alchemy Outputs your config file can't compute:

// alchemy.run.ts
export const Website = Cloudflare.Website.SvelteKit("Website", {
  kit: {
    paths: { base: "/docs" },
  },
});

No functions or plugins in the bag — preprocess, vitePlugin, and the other construction-time options belong in your sveltekit(...) call. Don't set an adapter in either place: Alchemy always injects its own wrangler-free Cloudflare adapter (a declared adapter is replaced with a warning).

404 behavior is driven by assets.notFoundHandling — the one knob configures both the build-time fallback-page generation and the assets layer that serves it. The generated 404 page renders the app shell, so kit's own error page shows:

// alchemy.run.ts
export const Website = Cloudflare.Website.SvelteKit("Website", {
  assets: {
    notFoundHandling: "404-page",
  },
});

Local dev

bun alchemy dev

alchemy dev runs SvelteKit's own Vite dev server — Node SSR with full HMR. platform.env carries the Worker's real Cloudflare bindings, served wrangler-free through the cloudflare-runtime platform proxy: calls like platform.env.CACHE.get(...) round-trip to a local workerd instance, so dev state is live and shared. Literal env values (strings and secrets) overlay the proxied bindings. Your server code is identical in dev and production.