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

main
mdx 184 lines 5.24 KB
Raw
1 ---
2 title: SvelteKit
3 description: Deploy a SvelteKit app to Railway with Railway.Website.SvelteKit — kit SSR plus prerendered assets on one Service, 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 `Railway.Website.SvelteKit` deploys a
13 [SvelteKit](https://svelte.dev/docs/kit) app to Railway. It builds
14 the app with SvelteKit's own Vite pipeline and an in-memory Node
15 adapter. Client assets and prerendered pages bake into a container
16 image; dynamic routes run in the kit handler on port 3000. Alchemy
17 creates a `Railway.Project` if you omit `project`, then a
18 `Railway.Service` from that image. `url` is the generated
19 `*.up.railway.app` hostname. Your `vite.config.ts` loads natively;
20 there is no `svelte.config.js` to write (kit v3 dropped it) and no
21 adapter 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 Railway from "@alchemy.run/railway";
53
54 export const Website = Railway.Website.SvelteKit("Website");
55 ```
56
57 Omit `project` to create a `Railway.Project` under the site
58 namespace. Pass an existing Project to share it with other services.
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: Railway.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 image
83 and served as static files first; server routes (`+server.ts`) and
84 server load functions run in the kit handler on the Service.
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 = Railway.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 Service 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 Service, so server routes read
107 the 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 A `svelte.config.js` on disk is an upstream error.
122
123 ```typescript
124 // vite.config.ts
125 import { sveltekit } from "@sveltejs/kit/vite";
126 import tailwindcss from "@tailwindcss/vite";
127 import { defineConfig } from "vite";
128
129 export default defineConfig({
130 plugins: [
131 tailwindcss(),
132 sveltekit({
133 prerender: { handleHttpError: "warn" },
134 }),
135 ],
136 });
137 ```
138
139 The `kit` prop on the resource is a deploy-time override layer merged
140 over those options (the override wins). It must be JSON-serializable:
141
142 ```typescript
143 // alchemy.run.ts
144 export const Website = Railway.Website.SvelteKit("Website", {
145 kit: {
146 paths: { base: "/docs" },
147 },
148 });
149 ```
150
151 Don't set `kit.adapter` — Alchemy injects its Node adapter (an
152 adapter declared in your `sveltekit(...)` call is replaced with a
153 warning).
154
155 ## Local dev
156
157 ```sh
158 bun alchemy dev
159 ```
160
161 `alchemy dev` runs SvelteKit's own Vite dev server — Node SSR with
162 full HMR — instead of deploying; `site.url` is the local address and
163 no Railway resources are created (`service` and `project` are
164 `undefined`). Wrap the site in
165 `Alchemy.remote()` to deploy the live Service even during dev.
166
167 ## Custom domain
168
169 ```typescript
170 const site = yield* Railway.Website.SvelteKit("Web", {
171 domain: "app.example.com",
172 });
173 ```
174
175 Alchemy attaches a [`Railway.CustomDomain`](/railway/networking)
176 (`targetPort` 3000). `url` becomes `https://app.example.com`. Point
177 DNS at Railway's verification records.
178
179 ## Where next
180
181 - [`SvelteKit` API](/providers/railway/website/sveltekit)
182 - [Projects](/railway/compute/projects) and
183 [Services](/railway/compute/services)
184 - [Custom domains](/railway/networking)