clover's git

the-knife

1	---
2	title: Astro
3	description: Package Astro SSR or prerendered pages for Neon Functions, with native Astro development.
4	sidebar:
5	order: 2
6	---
7
8	`Neon.Website.Astro` builds Astro's server handler and assets into a Node 24 Fetch
9	artifact for a Neon Function. Static files and SSR share that Function; there is
10	no container, listening server, or S3 hosting layer.
11
12	## Prepare the app
13
14	Use an existing Astro app or the
15	[runnable Astro example](https://github.com/alchemy-run/alchemy/tree/main/examples/neon-website-astro).
16	Configure [deployment credentials](/neon/setup), then install in the app directory:
17
18	Install [Alchemy and its matching Effect dependencies](/getting-started) first;
19	use Node 24 for this build toolchain.
20
21	```sh
22	pnpm add -D @alchemy.run/frontend-frameworks @vercel/nft
23	```
24
25	Keep integrations in `astro.config.*`, but omit `adapter`: the build integration
26	owns it. The constructor defaults to `output: "server"`, including when the
27	config file requests static output. Use the resource's `astro.output` to change it.
28
29	## Define the stack
30
31	```typescript
32	// alchemy.run.ts
33	import * as Alchemy from "alchemy";
34	import * as Neon from "alchemy/Neon";
35	import * as Effect from "effect/Effect";
36
37	export default Alchemy.Stack(
38	"NeonAstro",
39	{ providers: Neon.providers(), state: Alchemy.localState() },
40	Effect.gen(function* () {
41	const site = yield* Neon.Website.Astro("Web", {
42	rootDir: ".",
43	});
44	return { url: site.url };
45	}),
46	);
47	```
48
49	Pages render on demand; pages with `export const prerender = true` become static
50	assets. Serializable `astro` overrides include `site`, `base`, `srcDir`,
51	`publicDir`, `outDir`, and `trailingSlash`.
52
53	## Prerender the whole site
54
55	```diff lang="typescript"
56	const site = yield* Neon.Website.Astro("Web", {
57	rootDir: ".",
58	+ astro: { output: "static" },
59	});
60	```
61
62	Static mode packages the built pages without an Astro request handler. They are
63	still served by a Function, not a bucket. For a built `404.html`, set
64	`assets.notFoundHandling` to `"404-page"`; SSR misses otherwise go to Astro.
65
66	## Develop and deploy
67
68	```sh
69	pnpm exec alchemy dev
70	pnpm exec alchemy deploy
71	pnpm exec alchemy destroy
72	```
73
74	Run these separately: stop dev before deploying, and destroy when finished.
75	Development uses Astro's native server and HMR, returns a local URL, and creates
76	no implicit Neon resources. Append `.pipe(Alchemy.remote())` to the Website
77	Effect to opt into live deployment during dev.
78
79	Omitting scope creates an Ohio Project on live deploy. Pass either `project` or
80	`branch` to use an existing backend; use Ohio when combining with storage. Read
81	[scope and credential boundaries](/neon/frontend/vite#scope-and-credentials).
82	Server code can read private `env` values through `process.env`; `PUBLIC_*`
83	values may be embedded into browser code and must not contain secrets.
84
85	:::caution[Deployment limits]
86	Astro production builds and Fetch invocation have local coverage, not complete
87	live lifecycle acceptance. Code/env updates have served stale runtime content
88	in Neon probes. This constructor adds no CDN or image-optimization service;
89	custom-domain registration is not TLS validation. See the
90	[shared deployment limits](/neon/frontend/vite#environment-and-deployment-limits).
91	:::
92
93	## Reference
94
95	- [Astro API](/providers/neon/website/astro)
96	- [Runnable Astro example](https://github.com/alchemy-run/alchemy/tree/main/examples/neon-website-astro)