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

main
mdx 188 lines 5.37 KB
Raw
1 ---
2 title: SvelteKit
3 description: Deploy a SvelteKit app to Hetzner with Hetzner.Website.SvelteKit — kit SSR as a systemd unit on port 3000, prerendered assets baked into the unit, 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 `Hetzner.Website.SvelteKit` deploys a
13 [SvelteKit](https://svelte.dev/docs/kit) app to a Hetzner Cloud
14 Server. It builds the app with SvelteKit's own Vite pipeline and an
15 in-memory Node adapter. Client assets and prerendered pages bake into
16 the systemd unit; dynamic routes run in the kit handler on port 3000.
17 Alchemy creates a `cpx12` / `ubuntu-24.04` Server in `fsn1` if you
18 omit `server`, then a `Hetzner.Service` on that Server. The live URL
19 is `http://{ipv4}:3000`. Your `vite.config.ts` loads natively; there
20 is no `svelte.config.js` to write (kit v3 dropped it) and no adapter
21 to install.
22
23 ## Install
24
25 The build integration is not bundled with alchemy. Install
26 `@alchemy.run/frontend-frameworks`; the resource loads its
27 `/sveltekit` and `/sveltekit/node` exports from your project at
28 deploy time. It is only used at build time, so a dev dependency is
29 enough:
30
31 <PackageManagers dev={devDeps} />
32
33 ## Configure SvelteKit
34
35 Your project's `vite.config.ts` loads natively — your Vite plugins
36 and the kit options in your `sveltekit(...)` call all apply as usual.
37 Alchemy injects its Node adapter (replacing any adapter you declare,
38 with a warning), so a fresh SvelteKit project deploys as-is.
39 Deploy-specific kit overrides can also be passed via the `kit` prop,
40 which merges over your `sveltekit(...)` options — see
41 [Kit options](#kit-options) below. A project without a
42 `vite.config.*` works too: the resource falls back to a fully
43 programmatic build.
44
45 ## Declare the Website
46
47 Declare the site as a module-level const (rather than inline in the
48 Stack):
49
50 ```typescript
51 // alchemy.run.ts
52 import * as Hetzner from "@alchemy.run/hetzner";
53
54 export const Website = Hetzner.Website.SvelteKit("Website");
55 ```
56
57 Omit `server` to create a `cpx12` in `fsn1`. Pass an existing Server
58 so several sites or APIs share the VM.
59
60 ## Add it to the Stack
61
62 Yield the site from your Stack and return its URL:
63
64 ```typescript
65 // alchemy.run.ts
66 import * as Alchemy from "alchemy";
67 import * as Effect from "effect/Effect";
68
69 export default Alchemy.Stack(
70 "MySvelteKitSite",
71 {
72 providers: Hetzner.providers(),
73 state: Alchemy.localState(),
74 },
75 Effect.gen(function* () {
76 const site = yield* Website;
77 return { url: site.url };
78 }),
79 );
80 ```
81
82 Routes with `export const prerender = true` are baked into the unit
83 and served as static files first; server routes (`+server.ts`) and
84 server load functions run in the kit handler on the Server.
85
86 ## Add environment variables
87
88 Process environment is a top-level `env` map:
89
90 ```diff lang="typescript"
91 // alchemy.run.ts
92 export const Website = Hetzner.Website.SvelteKit("Website", {
93 + env: {
94 + GREETING: "Hello from alchemy",
95 + API_BASE: "https://api.example.com",
96 + },
97 });
98 ```
99
100 The values are copied onto `process.env` before the build (and the
101 dev server) and onto the systemd unit at deploy time, so server code
102 reads the same keys in both modes.
103
104 ## Read the environment in server code
105
106 The Kit server runs in Node on the 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 a deploy-time override layer merged
139 over those options (the override wins). It must be JSON-serializable:
140
141 ```typescript
142 // alchemy.run.ts
143 export const Website = Hetzner.Website.SvelteKit("Website", {
144 kit: {
145 paths: { base: "/docs" },
146 },
147 });
148 ```
149
150 Don't set `kit.adapter` — Alchemy injects its Node adapter (an
151 adapter declared in your `sveltekit(...)` call is replaced with a
152 warning).
153
154 ## Local dev
155
156 ```sh
157 bun alchemy dev
158 ```
159
160 `alchemy dev` runs SvelteKit's own Vite dev server — Node SSR with
161 full HMR — instead of deploying; `site.url` is the local address and
162 no Hetzner resources are created (`server` and `service` are
163 `undefined`). Wrap the site in `Alchemy.remote()` to deploy the live
164 Server even during dev.
165
166 ## Custom domain
167
168 `domain` requires an existing [`Hetzner.Zone`](/hetzner/networking/dns).
169 Alchemy creates an A RecordSet pointing at the Server's public IPv4.
170 There is no TLS on the Service — `url` is `http://{domain}:3000`.
171
172 ```typescript
173 const zone = yield* Hetzner.Zone("dns", { name: "example.com" });
174
175 const site = yield* Hetzner.Website.SvelteKit("Web", {
176 domain: "app.example.com",
177 zone,
178 });
179 ```
180
181 Passing `domain` without `zone` fails.
182
183 ## Where next
184
185 - [`SvelteKit` API](/providers/hetzner/website/sveltekit)
186 - [Servers](/hetzner/compute/servers) and
187 [Services](/hetzner/compute/services)
188 - [DNS](/hetzner/networking/dns)