@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 06:00 UTC

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