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

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