The best way to control Claude Code, Codex and more from any computer or phone

main
mdx 217 lines 6.5 KB
Raw
1 ---
2 title: SvelteKit
3 description: Deploy a SvelteKit app to Cloudflare Workers with Cloudflare.Website.SvelteKit — a wrangler-free in-memory adapter, real bindings on platform.env, and full-HMR local dev.
4 sidebar:
5 order: 11
6 ---
7
8 import PackageManagers from "../../../../components/PackageManagers.astro";
9
10 export const devDeps = "@alchemy.run/frontend-frameworks";
11
12 `Cloudflare.Website.SvelteKit` deploys a
13 [SvelteKit](https://svelte.dev/docs/kit) app as a Cloudflare Worker.
14 It builds the app with SvelteKit's own Vite pipeline and a
15 wrangler-free in-memory Cloudflare adapter, then re-bundles the
16 server output for workerd. Client assets and prerendered pages deploy
17 as Worker static assets; dynamic routes are served by the generated
18 Worker. Your `vite.config.ts` loads natively; there is no
19 `svelte.config.js` to write (kit v3 dropped it), no
20 `@sveltejs/adapter-cloudflare` to install, and no Wrangler file.
21
22 ## Install
23
24 The build integration is not bundled with alchemy. Install
25 `@alchemy.run/frontend-frameworks`; the resource loads its
26 `/sveltekit` export from your project at deploy time. It is only used at
27 build time, so a dev dependency is enough:
28
29 <PackageManagers dev={devDeps} />
30
31 ## Configure SvelteKit
32
33 Your project's `vite.config.ts` loads natively — your Vite plugins
34 and the kit options in your `sveltekit(...)` call all apply as usual.
35 Alchemy injects its own wrangler-free Cloudflare adapter (replacing
36 any adapter you declare, with a warning), so a fresh SvelteKit
37 project deploys as-is. Deploy-specific kit overrides can also be
38 passed via the `kit` prop, which merges over your `sveltekit(...)`
39 options — see [Kit options and 404 handling](#kit-options-and-404-handling)
40 below. A project without a `vite.config.*` works too: the resource
41 falls back to a fully programmatic build.
42
43 ## Declare the Website
44
45 Declare the site as a module-level const (rather than inline in the
46 Stack) and derive the typed shape of its bindings from it:
47
48 ```typescript
49 // alchemy.run.ts
50 import * as Cloudflare from "@alchemy.run/cloudflare";
51
52 export const Website = Cloudflare.Website.SvelteKit("Website");
53
54 export type WebsiteEnv = Cloudflare.InferEnv<typeof Website>;
55 ```
56
57 `WebsiteEnv` is the typed shape of the Worker's bindings, derived
58 from the class — you'll import it into your SvelteKit code in
59 [Read bindings in server code](#read-bindings-in-server-code).
60
61 ## Add it to the Stack
62
63 Yield the class from your Stack and return its URL:
64
65 ```typescript
66 // alchemy.run.ts
67 import * as Alchemy from "alchemy";
68 import * as Effect from "effect/Effect";
69
70 export default Alchemy.Stack(
71 "MySvelteKitSite",
72 {
73 providers: Cloudflare.providers(),
74 state: Cloudflare.state(),
75 },
76 Effect.gen(function* () {
77 const site = yield* Website;
78 return { url: site.url };
79 }),
80 );
81 ```
82
83 SvelteKit's server code is built for Node, so the `nodejs_compat`
84 compatibility flag is added automatically — you don't need to pass
85 it.
86
87 See
88 [examples/cloudflare-website-sveltekit](https://github.com/alchemy-run/alchemy/tree/main/examples/cloudflare-website-sveltekit)
89 for the checked-in example.
90
91 ## Add bindings
92
93 The resource returns a plain `Worker`, so `env` accepts the full
94 binding vocabulary — KV namespaces, R2 buckets, Durable Objects,
95 secrets:
96
97 ```diff lang="typescript"
98 // alchemy.run.ts
99 +import * as Config from "effect/Config";
100
101 +export const Cache = Cloudflare.KV.Namespace("Cache");
102
103 export const Website = Cloudflare.Website.SvelteKit("Website", {
104 + env: {
105 + CACHE: Cache,
106 + API_KEY: Config.Redacted("API_KEY"),
107 + },
108 });
109 ```
110
111 `Cache` is a description, not a deploy — Alchemy provisions the real
112 namespace because the Website binds it. `Config.Redacted` reads
113 `API_KEY` from your environment at deploy time and binds it as a
114 Worker secret — see [Secrets & env](/cloudflare/security/secrets-env).
115
116 ## Read bindings in server code
117
118 Server routes read bindings through SvelteKit's `platform.env`. Type
119 it once by augmenting `App.Platform` with the inferred env type:
120
121 ```typescript
122 // src/app.d.ts
123 import type { WebsiteEnv } from "../alchemy.run.ts";
124
125 declare global {
126 namespace App {
127 interface Platform {
128 env: WebsiteEnv;
129 }
130 }
131 }
132
133 export {};
134 ```
135
136 Every server route now gets fully typed bindings:
137
138 ```typescript
139 // src/routes/+page.server.ts
140 export const load = async ({ platform }) => {
141 const cached = await platform?.env?.CACHE.get("greeting");
142 return { greeting: cached ?? "hello" };
143 };
144 ```
145
146 `platform.env.CACHE` is typed as a KV namespace and
147 `platform.env.API_KEY` as a string — renaming a binding in
148 `alchemy.run.ts` is a type error in your routes.
149
150 ## Kit options and 404 handling
151
152 Since kit v3 there is no `svelte.config.js` — kit options live in the
153 `sveltekit(...)` call in your `vite.config.ts`, which loads natively:
154
155 ```typescript
156 // vite.config.ts
157 import { sveltekit } from "@sveltejs/kit/vite";
158 import tailwindcss from "@tailwindcss/vite";
159 import { defineConfig } from "vite";
160
161 export default defineConfig({
162 plugins: [
163 tailwindcss(),
164 sveltekit({
165 prerender: { handleHttpError: "warn" },
166 }),
167 ],
168 });
169 ```
170
171 The `kit` prop is the deploy-time override bag: JSON-serializable kit
172 config merged over your own `sveltekit(...)` options (the prop wins).
173 Use it for per-stage values or alchemy `Output`s your config file
174 can't compute:
175
176 ```typescript
177 // alchemy.run.ts
178 export const Website = Cloudflare.Website.SvelteKit("Website", {
179 kit: {
180 paths: { base: "/docs" },
181 },
182 });
183 ```
184
185 No functions or plugins in the bag — `preprocess`, `vitePlugin`, and
186 the other construction-time options belong in your `sveltekit(...)`
187 call. Don't set an `adapter` in either place: Alchemy always injects
188 its own wrangler-free Cloudflare adapter (a declared adapter is
189 replaced with a warning).
190
191 404 behavior is driven by `assets.notFoundHandling` — the one knob
192 configures both the build-time fallback-page generation and the
193 assets layer that serves it. The generated 404 page renders the app
194 shell, so kit's own error page shows:
195
196 ```typescript
197 // alchemy.run.ts
198 export const Website = Cloudflare.Website.SvelteKit("Website", {
199 assets: {
200 notFoundHandling: "404-page",
201 },
202 });
203 ```
204
205 ## Local dev
206
207 ```sh
208 bun alchemy dev
209 ```
210
211 `alchemy dev` runs SvelteKit's own Vite dev server — Node SSR with
212 full HMR. `platform.env` carries the Worker's real Cloudflare
213 bindings, served wrangler-free through the cloudflare-runtime
214 platform proxy: calls like `platform.env.CACHE.get(...)` round-trip
215 to a local workerd instance, so dev state is live and shared. Literal
216 `env` values (strings and secrets) overlay the proxied bindings. Your
217 server code is identical in dev and production.