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

main
mdx 194 lines 5.67 KB
Raw
1 ---
2 title: SvelteKit
3 description: Deploy a SvelteKit app to AWS with AWS.Website.SvelteKit — SSR on a Lambda Web Function, assets and prerendered pages on S3 + CloudFront, and Kit's own dev server under alchemy dev.
4 sidebar:
5 order: 12
6 ---
7
8 import PackageManagers from "../../../../components/PackageManagers.astro";
9
10 export const devDeps = "@alchemy.run/frontend-frameworks";
11
12 `AWS.Website.SvelteKit` deploys a
13 [SvelteKit](https://svelte.dev/docs/kit) app to AWS. It builds the
14 app with SvelteKit's own Vite pipeline and a wrangler-free in-memory
15 Node adapter; the server runs on a
16 [Lambda Web Function](/aws/compute/web-functions). Client assets and
17 prerendered pages are served from a private S3 bucket through
18 CloudFront; dynamic routes stream from the server. Your
19 `vite.config.ts` loads natively; there is no `svelte.config.js` to
20 write (kit v3 dropped it) and no adapter to install.
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` and `/sveltekit/node` exports from your project at deploy
27 time. It is only used at 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 AWS adapter (replacing any
36 adapter you declare, with a warning), so a fresh SvelteKit project
37 deploys as-is. Deploy-specific kit overrides can also be passed via
38 the `kit` prop, which merges over your `sveltekit(...)` options — see
39 [Kit options](#kit-options) below. A project without a
40 `vite.config.*` works too: the resource falls back to a fully
41 programmatic build.
42
43 ## Declare the Website
44
45 Declare the site as a module-level const (rather than inline in the
46 Stack):
47
48 ```typescript
49 // alchemy.run.ts
50 import * as AWS from "@alchemy.run/aws";
51
52 export const Website = AWS.Website.SvelteKit("Website");
53 ```
54
55 ## Add it to the Stack
56
57 Yield the site from your Stack and return its URL:
58
59 ```typescript
60 // alchemy.run.ts
61 import * as Alchemy from "alchemy";
62 import * as Effect from "effect/Effect";
63
64 export default Alchemy.Stack(
65 "MySvelteKitSite",
66 {
67 providers: AWS.providers(),
68 state: AWS.state(),
69 },
70 Effect.gen(function* () {
71 const site = yield* Website;
72 return { url: site.url };
73 }),
74 );
75 ```
76
77 Routes with `export const prerender = true` are uploaded to S3 and
78 served from the edge without invoking the server; server routes
79 (`+server.ts`) and server load functions stream from the server.
80
81 See
82 [examples/aws-website-sveltekit](https://github.com/alchemy-run/alchemy/tree/main/examples/aws-website-sveltekit)
83 for the checked-in example.
84
85 ## Add environment variables
86
87 The server function's environment is configured under `env` — plain
88 values, or outputs from other resources in the Stack:
89
90 ```diff lang="typescript"
91 // alchemy.run.ts
92 export const Website = AWS.Website.SvelteKit("Website", {
93 + env: {
94 + GREETING: "Hello from alchemy",
95 + API_BASE: api.url,
96 + },
97 });
98 ```
99
100 The values are set on the server at deploy time and injected into the
101 dev server's process environment under `alchemy dev`, so server code
102 reads the same values in both modes.
103
104 ## Read the environment in server code
105
106 The Kit server is a plain Node server, so server routes read the
107 environment from `process.env` (or kit's `$env/dynamic/private`,
108 which is initialized from it):
109
110 ```typescript
111 // src/routes/+page.server.ts
112 export const load = () => {
113 return { greeting: process.env.GREETING ?? "hello" };
114 };
115 ```
116
117 ## Kit options
118
119 Since kit v3 there is no `svelte.config.js` — kit options live in the
120 `sveltekit(...)` call in your `vite.config.ts`, which loads natively:
121
122 ```typescript
123 // vite.config.ts
124 import { sveltekit } from "@sveltejs/kit/vite";
125 import tailwindcss from "@tailwindcss/vite";
126 import { defineConfig } from "vite";
127
128 export default defineConfig({
129 plugins: [
130 tailwindcss(),
131 sveltekit({
132 prerender: { handleHttpError: "warn" },
133 }),
134 ],
135 });
136 ```
137
138 The `kit` prop on the resource is the deploy-time override bag:
139 JSON-serializable kit config merged over those options (the prop
140 wins). Use it for per-stage values or alchemy `Output`s your config
141 file can't compute:
142
143 ```typescript
144 // alchemy.run.ts
145 export const Website = AWS.Website.SvelteKit("Website", {
146 kit: {
147 paths: { base: "/docs" },
148 },
149 });
150 ```
151
152 No functions or plugins in the bag — `preprocess`, `vitePlugin`, and
153 the other construction-time options belong in your `sveltekit(...)`
154 call. Don't set `kit.adapter` — Alchemy injects its own wrangler-free
155 AWS adapter (an adapter declared in your `sveltekit(...)` call is
156 replaced with a warning).
157
158 ## Run on a Lambda Function
159
160 Web Functions run in a subset of Regions. Elsewhere, set
161 `server: "function"`: the app builds with the `/sveltekit/aws` deploy target
162 and runs on a Lambda Function behind a streaming Function URL, tuned with
163 `memorySize`, `architecture`, and `runtime`:
164
165 ```diff lang="typescript"
166 // alchemy.run.ts
167 export const Website = AWS.Website.SvelteKit("Website", {
168 + server: "function",
169 + memorySize: 2048,
170 });
171 ```
172
173 ## Local dev
174
175 ```sh
176 bun alchemy dev
177 ```
178
179 `alchemy dev` runs SvelteKit's own Vite dev server — Node SSR with
180 full HMR, which is already the AWS Lambda programming model
181 (`process.env` included) — instead of deploying; `site.url` is the
182 local address and no AWS resources are created. Wrap the site in
183 `Alchemy.remote()` to deploy the real infrastructure even during dev.
184
185 ## Custom domain
186
187 ```typescript
188 const site = yield* AWS.Website.SvelteKit("Web", {
189 domain: { name: "app.example.com" },
190 });
191 ```
192
193 The hosted zone is inferred from the hostname. Pass `hostedZoneId` to
194 pin it when several zones could match.