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

main
mdx 239 lines 7.23 KB
Raw
1 ---
2 title: SolidStart
3 description: Deploy a SolidStart app to Hetzner with Hetzner.Website.SolidStart — nitro's node preset as a systemd unit on port 3000, prerendered pages baked into the unit, and SolidStart's own Vite dev server under alchemy dev.
4 sidebar:
5 order: 10.5
6 ---
7
8 import PackageManagers from "../../../../components/PackageManagers.astro";
9
10 export const devDeps = "@alchemy.run/frontend-frameworks";
11
12 `Hetzner.Website.SolidStart` deploys a
13 [SolidStart](https://start.solidjs.com) app to a Hetzner Cloud Server.
14 It runs your project's own `vite build` and appends nitro's `node`
15 preset: the SSR server runs as a systemd
16 [`Hetzner.Service`](/hetzner/compute/services) on port 3000, and
17 client assets plus prerendered pages are baked into the unit and
18 served first. Omit `server` and Alchemy creates a `cpx12` Ubuntu
19 24.04 box in `fsn1`. The live URL is `http://{ipv4}:3000` — the
20 Service has no TLS. No adapter.
21
22 :::note[Verified version line]
23 This page tracks `@solidjs/start` **2.x** with
24 `@solidjs/vite-plugin-nitro-2` — the Vite-native line where
25 `solidStart()` is a plain Vite plugin and nitro is a second plugin.
26 :::
27
28 ## Install
29
30 The build integration is not bundled with alchemy. Install
31 `@alchemy.run/frontend-frameworks`; the resource loads its
32 `/solidstart` and `/solidstart/node` exports from your project at
33 deploy time. It is only used at build time, so a dev dependency is
34 enough:
35
36 <PackageManagers dev={devDeps} />
37
38 `@solidjs/vite-plugin-nitro-2` is the server half of a SolidStart
39 build and must be a project dependency too:
40
41 <PackageManagers add="@solidjs/vite-plugin-nitro-2" />
42
43 ## Configure Vite
44
45 Your `vite.config.ts` is the SolidStart plugin — no adapter, no
46 nitro wiring. Vite plugins like Tailwind go in `plugins` as usual:
47
48 ```typescript
49 // vite.config.ts
50 import { solidStart } from "@solidjs/start/config";
51 import tailwindcss from "@tailwindcss/vite";
52 import { defineConfig } from "vite";
53
54 export default defineConfig({
55 plugins: [solidStart(), tailwindcss()],
56 });
57 ```
58
59 Alchemy appends its own `nitroV2Plugin()` instance at build time,
60 carrying nitro's `node` preset. Don't register `nitroV2Plugin()`
61 yourself — the appended instance would discard its options, so the
62 build fails with an actionable error instead. Pass nitro options
63 through the resource's `nitro` prop; see [Prerendering](#prerendering)
64 below.
65
66 ## Declare the Website
67
68 Declare the site as a module-level const (rather than inline in the
69 Stack):
70
71 ```typescript
72 // alchemy.run.ts
73 import * as Hetzner from "@alchemy.run/hetzner";
74
75 export const Website = Hetzner.Website.SolidStart("Website");
76 ```
77
78 Pass `server` to host the site on an existing
79 [`Hetzner.Server`](/hetzner/compute/servers) — several sites and
80 APIs can share one box. `rootDir` is the project root — the directory
81 holding `package.json` and `vite.config.*`. It defaults to `"."`, so
82 set it only when the app does not sit next to `alchemy.run.ts`:
83
84 ```typescript
85 export const Website = Hetzner.Website.SolidStart("Website", {
86 rootDir: "./app",
87 });
88 ```
89
90 ## Add it to the Stack
91
92 Yield the site from your Stack and return its URL:
93
94 ```typescript
95 // alchemy.run.ts
96 import * as Alchemy from "alchemy";
97 import * as Effect from "effect/Effect";
98
99 export default Alchemy.Stack(
100 "MySolidStartSite",
101 {
102 providers: Hetzner.providers(),
103 state: Alchemy.localState(),
104 },
105 Effect.gen(function* () {
106 const site = yield* Website;
107 return { url: site.url };
108 }),
109 );
110 ```
111
112 The live `url` is `http://{ipv4}:3000`. `site.server` and
113 `site.service` are the Hetzner resources underneath — `undefined`
114 during `alchemy dev`.
115
116 See the [SolidStart API reference](/providers/hetzner/website/solidstart)
117 for every prop and attribute.
118
119 ## Add environment variables
120
121 Process environment is a top-level `env` map — plain strings, or
122 `Redacted` values:
123
124 ```diff lang="typescript"
125 // alchemy.run.ts
126 export const Website = Hetzner.Website.SolidStart("Website", {
127 + env: {
128 + API_BASE: "https://api.example.com",
129 + },
130 });
131 ```
132
133 The values are copied onto `process.env` before the build and the
134 dev server, and onto the systemd unit at deploy time, so server
135 code reads the same keys in both modes. Client inlining is whatever
136 Vite does (`VITE_` prefixes).
137
138 An output from another resource only exists once that resource is
139 yielded, so declare the site inside the Stack generator instead:
140
141 ```typescript
142 // alchemy.run.ts
143 Effect.gen(function* () {
144 const api = yield* Api;
145
146 const site = yield* Hetzner.Website.SolidStart("Website", {
147 env: { API_BASE: api.url },
148 });
149
150 return { url: site.url };
151 });
152 ```
153
154 ## Read the environment in server code
155
156 The SolidStart server is a plain Node process, so API routes,
157 server functions, and SSR read the environment from `process.env`:
158
159 ```typescript
160 // src/routes/api/hello.ts
161 export function GET() {
162 return new Response(process.env.API_BASE ?? "unset");
163 }
164 ```
165
166 Values prefixed `VITE_` are inlined into the client bundle at build
167 time instead, as `import.meta.env.VITE_*` — set those in the shell
168 that runs `alchemy deploy`, not in `env`.
169
170 ## Prerendering
171
172 Nitro renders the routes you list at build time into `.output/public`.
173 They are baked into the unit and served as static files with no
174 handler invocation:
175
176 ```typescript
177 export const Website = Hetzner.Website.SolidStart("Website", {
178 nitro: { prerender: { routes: ["/", "/about"] } },
179 });
180 ```
181
182 `prerender` takes the routes to render (`routes`) and can crawl links
183 from prerendered pages to prerender them too (`crawlLinks`). The
184 `nitro` prop is the home for all nitro options (route rules, storage,
185 ...) — the integration owns the plugin instance, so they cannot live
186 in `vite.config.ts`. Values must be JSON-serializable; `preset` is
187 owned by the Node deploy target, and a foreign preset is a hard error.
188
189 ## Local dev
190
191 ```sh
192 bun alchemy dev
193 ```
194
195 `alchemy dev` runs SolidStart's own Vite dev server (native HMR)
196 instead of deploying; `site.url` is the local address and no Hetzner
197 resources are created. Nitro plays no part in dev. Wrap the site in
198 `Alchemy.remote()` to deploy the live Server and Service even during
199 dev:
200
201 ```typescript
202 export const Website = Hetzner.Website.SolidStart("Website").pipe(
203 Alchemy.remote(),
204 );
205 ```
206
207 SolidStart's plugin resolves its app root and route directory from
208 the process working directory, so one `alchemy dev` process serves
209 one SolidStart app at a time.
210
211 :::caution[Run `alchemy dev` under Node]
212 SolidStart 2's dev server answers requests through `srvx/node`, which
213 returns the string `[object Object]` instead of the rendered document
214 when it runs under Bun. Production builds are unaffected — only the
215 dev server is. Until that upstream gap closes, run `alchemy dev` with
216 Node (`npx alchemy dev`) for SolidStart projects.
217 :::
218
219 ## Custom domain
220
221 ```typescript
222 const zone = yield* Hetzner.Zone("dns", { name: "example.com" });
223 const site = yield* Hetzner.Website.SolidStart("Web", {
224 domain: "app.example.com",
225 zone,
226 });
227 ```
228
229 `domain` requires an existing [`Hetzner.Zone`](/hetzner/networking/dns)
230 — the Website does not create one. It adds an A record pointing at
231 the Server's public IPv4. `url` becomes `http://app.example.com:3000`.
232 There is no TLS on the Service.
233
234 ## Where next
235
236 - [SolidStart API reference](/providers/hetzner/website/solidstart)
237 - [Servers](/hetzner/compute/servers) and
238 [Services](/hetzner/compute/services)
239 - [DNS](/hetzner/networking/dns)