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

main
mdx 237 lines 6.93 KB
Raw
1 ---
2 title: Astro
3 description: Deploy an Astro app to Hetzner with Hetzner.Website.Astro — Node SSR as a systemd unit on a Server, static output as a file server, and Astro's own dev server under alchemy 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 `Hetzner.Website.Astro` deploys an [Astro](https://astro.build)
13 project to a Hetzner Cloud Server as a systemd unit.
14 Server-rendered pages run on a
15 [`Hetzner.Service`](/hetzner/compute/services) (port 3000); static
16 files are served first, then the Astro handler. Omit `server` and
17 Alchemy creates a `cpx12` Ubuntu 24.04 Server in `fsn1`. The live
18 URL is `http://{ipv4}:3000` — there is no TLS on the Service. Your
19 `astro.config.*` loads natively — don't declare an `adapter`.
20
21 ## Install
22
23 The build integration is not bundled with alchemy. Install
24 `@alchemy.run/frontend-frameworks`; the resource loads its `/astro`
25 and `/astro/node` exports from your project at deploy time. It is
26 only used at build time, so a dev dependency is enough:
27
28 <PackageManagers dev={devDeps} />
29
30 ## Configure Astro
31
32 Your `astro.config.*` file loads natively — integrations, Vite
33 plugins, and any other non-serializable options work exactly as they
34 do outside Alchemy. Alchemy merges a programmatic config *over* it:
35 the Node adapter is injected for you (don't declare an `adapter` in
36 your config — that fails the build with an actionable error), and
37 options passed via the `astro` prop override the file's — see
38 [Astro configuration](#astro-configuration) below for the details.
39
40 ## Declare the Website
41
42 Declare the site as a module-level const (rather than inline in the
43 Stack):
44
45 ```typescript
46 // alchemy.run.ts
47 import * as Hetzner from "@alchemy.run/hetzner";
48
49 export const Website = Hetzner.Website.Astro("Website");
50 ```
51
52 Pass `rootDir` if `package.json` is not at `.`. Pass `server` to
53 run the unit on a Server you already declared — several sites and
54 APIs can share one VM. Otherwise the site creates a `cpx12` /
55 `ubuntu-24.04` Server in `fsn1`.
56
57 ```diff lang="typescript"
58 +export const Box = Hetzner.Server("Box", {
59 + serverType: "cpx12",
60 + image: "ubuntu-24.04",
61 + location: "fsn1",
62 +});
63 +
64 export const Website = Hetzner.Website.Astro("Website", {
65 + server: Box,
66 });
67 ```
68
69 ## Add it to the Stack
70
71 Yield the site from your Stack and return its URL:
72
73 ```typescript
74 // alchemy.run.ts
75 import * as Alchemy from "alchemy";
76 import * as Effect from "effect/Effect";
77
78 export default Alchemy.Stack(
79 "MyAstroSite",
80 {
81 providers: Hetzner.providers(),
82 state: Alchemy.localState(),
83 },
84 Effect.gen(function* () {
85 const site = yield* Website;
86 return { url: site.url };
87 }),
88 );
89 ```
90
91 Pages are server-rendered by default. Pages that
92 `export const prerender = true` are prerendered at build time and
93 served as static files.
94
95 On deploy `site.url` is `http://{ipv4}:3000` (or
96 `http://{domain}:3000` when you set `domain`). `site.server` and
97 `site.service` are undefined under `alchemy dev`.
98
99 ## Add environment variables
100
101 Process environment is the top-level `env` prop — plain strings, or
102 `Redacted` values. They are copied onto `process.env` before build
103 and `alchemy dev`, and onto the systemd unit at deploy:
104
105 ```diff lang="typescript"
106 // alchemy.run.ts
107 export const Website = Hetzner.Website.Astro("Website", {
108 + env: {
109 + GREETING: "Hello from Alchemy!",
110 + API_BASE: "https://api.example.com",
111 + },
112 });
113 ```
114
115 This is the hosted Node process, not Worker bindings.
116
117 ## Read the environment in server code
118
119 The Astro server runs in Node on the Server, so server-rendered
120 pages and endpoints read the environment from `process.env`:
121
122 ```astro
123 ---
124 // src/pages/index.astro
125 const greeting = process.env.GREETING ?? "hello";
126 ---
127
128 <h1>{greeting}</h1>
129 ```
130
131 Astro inlines `PUBLIC_*` keys at build time. Because `env` is
132 applied before the build, those keys behave the same as in a local
133 `astro build`.
134
135 ## Fully static sites
136
137 With `astro: { output: "static" }` every page is prerendered at
138 build time and the deploy is assets-only — no Astro handler, just a
139 static-file server as the systemd unit:
140
141 ```typescript
142 export const Website = Hetzner.Website.Astro("Website", {
143 astro: { output: "static" },
144 assets: { notFoundHandling: "404-page" },
145 });
146 ```
147
148 `assets.notFoundHandling` applies only to `output: "static"`.
149 `"404-page"` serves the built `404.html` for unmatched routes;
150 `"single-page-application"` answers misses with the index page
151 (200) instead.
152
153 ## Astro configuration
154
155 Your `astro.config.*` is the primary place to configure Astro —
156 integrations, Vite plugins, and every other option (serializable or
157 not) work as usual:
158
159 ```typescript
160 // astro.config.ts
161 import { defineConfig } from "astro/config";
162 import react from "@astrojs/react";
163 import tailwindcss from "@tailwindcss/vite";
164
165 export default defineConfig({
166 site: "https://blog.example.com",
167 integrations: [react()],
168 vite: {
169 plugins: [tailwindcss()],
170 },
171 });
172 ```
173
174 The `astro` prop on the resource exposes common serializable options
175 for deploy-specific overrides; Astro merges them *over* the config
176 file (scalars override, arrays like `integrations` and
177 `vite.plugins` concatenate after the file's):
178
179 ```typescript
180 // alchemy.run.ts
181 export const Website = Hetzner.Website.Astro("Website", {
182 astro: {
183 site: "https://preview.example.com",
184 },
185 });
186 ```
187
188 Two options are managed for you regardless of the config file:
189
190 - `adapter` — Alchemy injects the Node adapter. Declaring an
191 adapter in `astro.config.*` fails the build with an actionable
192 error.
193 - `output` — Alchemy defaults it to `"server"` (superseding a
194 file-level `output`), so pages render on demand on the Server.
195 Opt into a fully prerendered site with `astro: { output: "static" }`
196 on the resource.
197
198 `site`, `base`, `srcDir`, `publicDir`, `outDir`, and
199 `trailingSlash` are the other serializable keys on `astro`.
200
201 ## Local dev
202
203 `alchemy dev` runs Astro's own dev server (native HMR) instead of
204 deploying; `site.url` is the local address and no Hetzner resources
205 are created. Wrap the site in `Alchemy.remote()` to deploy the real
206 Server and Service even during dev.
207
208 ## Custom domain
209
210 `domain` requires an existing [`Hetzner.Zone`](/hetzner/networking/dns)
211 — the Website does not create a zone. It adds an A RecordSet
212 pointing at the Server's public IPv4, and `url` becomes
213 `http://{domain}:3000`. There is no TLS on the Service:
214
215 ```typescript
216 export const Dns = Hetzner.Zone("Dns", {
217 name: "example.com",
218 });
219
220 export const Website = Hetzner.Website.Astro("Website", {
221 domain: "app.example.com",
222 zone: Dns,
223 });
224 ```
225
226 Passing `domain` without `zone` fails.
227
228 ## Where next
229
230 - [`Hetzner.Website.Astro` reference](/providers/hetzner/website/astro)
231 — every prop and attribute.
232 - [Services](/hetzner/compute/services) and
233 [Servers](/hetzner/compute/servers) — the unit and VM the site
234 creates.
235 - [Zones & records](/hetzner/networking/dns) — the Zone `domain`
236 requires.
237 - [Setup](/hetzner/setup) — project, API token, and alchemy login.