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

main
ts 415 lines 15.9 KB
Raw
1 import type { MemoOptions } from "alchemy/Command/Memo";
2 import type { InputProps } from "alchemy/Input";
3 import { effectClass } from "alchemy/Util/effect";
4 import { resolveAstroSettings } from "alchemy/Website/AstroOutput";
5 import * as Effect from "effect/Effect";
6 import { Namespace } from "../KV/Namespace.ts";
7 import type { Providers } from "../Providers.ts";
8 import type { AssetsConfig } from "../Workers/Assets.ts";
9 import {
10 Worker,
11 type NormalizedBindings,
12 type WorkerAssetsConfig,
13 type WorkerBindingProps,
14 type WorkerProps,
15 } from "../Workers/Worker.ts";
16
17 export interface AstroProps<Bindings extends WorkerBindingProps = {}> extends Omit<
18 WorkerProps<Bindings>,
19 "vite" | "main" | "assets" | "source" | "script" | "bundle" | "rules"
20 > {
21 /**
22 * Astro project root directory.
23 * Defaults to the current working directory (`process.cwd()`).
24 */
25 rootDir?: string;
26 /**
27 * A custom Worker entry that wraps Astro's handler and adds exports of its
28 * own (Durable Object classes, a `scheduled` handler, ...). Import the Astro
29 * handler from `@alchemy.run/frontend-frameworks/astro/entrypoints/server`
30 * and re-export or extend its `default`:
31 *
32 * ```ts
33 * import handler from "@alchemy.run/frontend-frameworks/astro/entrypoints/server";
34 * export { MyDurableObject } from "./do.ts";
35 * export default { ...handler, scheduled: async () => {} };
36 * ```
37 *
38 * A relative path resolves against {@link rootDir}; a bare specifier resolves
39 * as a package import. When unset, Astro's server entrypoint is deployed.
40 */
41 main?: string;
42 /**
43 * Controls which files are hashed to decide whether a rebuild is needed.
44 * By default every non-gitignored file under `rootDir` is hashed, plus the
45 * nearest package-manager lockfile. Provide explicit globs to narrow the
46 * scope.
47 */
48 memo?: MemoOptions & {
49 /**
50 * Additional workspace directories to hash (relative to `rootDir`).
51 * By default (`"auto"`), workspaces are auto-detected from the build's
52 * module graph; an explicit array pins them.
53 * @default "auto"
54 */
55 workspaces?: "auto" | Array<MemoOptions & { cwd: string }>;
56 };
57 /**
58 * The name of the KV binding backing Astro's session API.
59 *
60 * A KV namespace is auto-provisioned and bound under this name on
61 * deploy, so `Astro.session` works with zero configuration. Bind your
62 * own KV namespace under this name in `env` to use it instead of the
63 * auto-provisioned one, or set this to `false` to disable session
64 * provisioning entirely.
65 * @default "SESSION"
66 */
67 sessionKVBindingName?: string | false;
68 /**
69 * Runtime used to prerender static pages. `"workerd"` renders them in the
70 * production Worker runtime; `"node"` uses Astro's stock Node prerenderer.
71 * @default "workerd"
72 */
73 prerenderEnvironment?: "workerd" | "node";
74 /**
75 * Deploy-time Astro config overrides, merged OVER your natively-loaded
76 * `astro.config.*` (values here win). Use it for values that vary per
77 * stage or derive from other resources' Outputs — everything else
78 * belongs in the config file.
79 */
80 astro?: {
81 /** Deployed URL origin (astro's `site`). */
82 site?: string;
83 /** Base path the site is served from (astro's `base`). */
84 base?: string;
85 /**
86 * Astro output target — a deploy-topology decision (whether Worker
87 * code runs at request time). `"server"` renders pages on demand in
88 * the Worker; individual pages opt into prerendering with
89 * `export const prerender = true`. `"static"` prerenders every page
90 * at build time and deploys assets-only. Overrides the `output` in
91 * your `astro.config.*`; leave it unset to use the file's value.
92 * @default the config file's `output`, else `"server"`
93 */
94 output?: "server" | "static";
95 /** Source directory (astro's `srcDir`). */
96 srcDir?: string;
97 /** Public assets directory (astro's `publicDir`). */
98 publicDir?: string;
99 /** Build output directory (astro's `outDir`). */
100 outDir?: string;
101 /** Trailing-slash handling (astro's `trailingSlash`). */
102 trailingSlash?: "always" | "never" | "ignore";
103 };
104 /**
105 * Path to an alternate astro config file, relative to `rootDir`.
106 * Defaults to astro's own config discovery.
107 */
108 config?: string;
109 /**
110 * Optional configuration for static asset routing behavior.
111 * Supports `runWorkerFirst`, `htmlHandling`, `notFoundHandling`, etc.
112 */
113 assets?: AssetsConfig;
114 }
115
116 // These options are inspected while constructing the Worker. Resolve them in
117 // the outer props Effect; pass-through properties can remain deferred Inputs.
118 type AstroInput<Bindings extends WorkerBindingProps> = InputProps<
119 AstroProps<Bindings>,
120 "sessionKVBindingName" | "astro" | "env" | "rootDir" | "config"
121 >;
122
123 /**
124 * A Cloudflare Worker deployed from an [Astro](https://astro.build)
125 * project.
126 *
127 * `Astro` runs Astro's programmatic build with a wrangler-free
128 * Cloudflare adapter (`@alchemy.run/frontend-frameworks/astro`): server-rendered pages
129 * execute in the Worker, prerendered pages and client assets deploy as
130 * static assets. Your `astro.config.*` loads natively — no adapter
131 * setup or Wrangler configuration required.
132 *
133 * Input files are content-hashed (respecting `.gitignore` by default)
134 * so unchanged projects skip the build and deploy entirely.
135 *
136 * The `@alchemy.run/frontend-frameworks` package must be installed in your
137 * project; its `/astro` export is loaded dynamically at deploy time:
138 *
139 * ```sh
140 * bun add -d @alchemy.run/frontend-frameworks
141 * ```
142 *
143 *
144 * ### Deploying an Astro Site
145 * A single call builds the project and deploys the server bundle plus
146 * static assets. Pages are server-rendered by default; pages that
147 * `export const prerender = true` are served as static assets. Astro's
148 * server runtime is built against Node APIs, so `nodejs_compat` is
149 * always included in the Worker's compatibility flags.
150 *
151 * **Example:** Astro site
152 * ```typescript
153 * const site = yield* Cloudflare.Website.Astro("Website");
154 * ```
155 *
156 * ### Static Sites
157 * When your `astro.config.*` or `astro: { output: "static" }` declares
158 * `output: "static"`, every page is prerendered at build time and the
159 * deploy is **assets-only**: no server bundle is uploaded —
160 * Cloudflare's asset layer answers every request (serve the built
161 * `404.html` via `assets: { notFoundHandling: "404-page" }`). Session
162 * provisioning is skipped for static sites since no Worker
163 * code runs at request time.
164 *
165 * **Example:** Fully static Astro site
166 * ```typescript
167 * const site = yield* Cloudflare.Website.Astro("Docs", {
168 * astro: { output: "static" },
169 * assets: {
170 * notFoundHandling: "404-page",
171 * },
172 * });
173 * ```
174 *
175 * ### Bindings
176 * Bind resources through `env` like any other Worker. Astro code reads
177 * them via `import { env } from "cloudflare:workers"` (or
178 * `Astro.locals.runtime.env`).
179 *
180 * **Example:** Astro site with a KV namespace and an R2 bucket
181 * ```typescript
182 * const kv = yield* Cloudflare.KV.Namespace("Cache");
183 * const bucket = yield* Cloudflare.R2.Bucket("Uploads");
184 *
185 * const site = yield* Cloudflare.Website.Astro("Website", {
186 * env: {
187 * CACHE: kv,
188 * UPLOADS: bucket,
189 * },
190 * });
191 * ```
192 *
193 * ### Sessions
194 * Astro's session API is backed by a KV namespace. One is provisioned
195 * and bound under the session binding name (`SESSION` by default)
196 * automatically, so `Astro.session` works with zero configuration.
197 * Bind your own namespace under that name to use it instead, or set
198 * `sessionKVBindingName: false` to opt out of session provisioning.
199 *
200 * **Example:** Bringing your own session namespace
201 * ```typescript
202 * const sessions = yield* Cloudflare.KV.Namespace("Sessions");
203 *
204 * const site = yield* Cloudflare.Website.Astro("Website", {
205 * env: {
206 * SESSION: sessions,
207 * },
208 * });
209 * ```
210 *
211 * **Example:** Opting out of session provisioning
212 * ```typescript
213 * const site = yield* Cloudflare.Website.Astro("Website", {
214 * sessionKVBindingName: false,
215 * });
216 * ```
217 *
218 * ### Route Caching
219 * Astro's route cache works with Workers Cache. Set the cache provider to
220 * `cacheCloudflare()` and Workers Cache is turned on for the Worker. Pages
221 * then go to the edge cache with the rules you give in `routeRules` or
222 * `Astro.cache.set()`. A response with no cache rule is not cached. Set
223 * `cache` on the site to override the Worker cache settings.
224 *
225 * **Example:** Caching a route at the edge
226 * ```typescript
227 * // astro.config.mjs
228 * import { defineConfig } from "astro/config";
229 * import { cacheCloudflare } from "@alchemy.run/frontend-frameworks/astro/cache";
230 *
231 * export default defineConfig({
232 * cache: { provider: cacheCloudflare() },
233 * routeRules: { "/insights": { maxAge: 600, swr: 86400 } },
234 * });
235 * ```
236 *
237 * ```typescript
238 * // alchemy.run.ts
239 * const site = yield* Cloudflare.Website.Astro("Website");
240 * ```
241 *
242 * ### Custom Worker Entry
243 * By default the deployed Worker entry is Astro's server entrypoint.
244 * When the Worker must export more than Astro's fetch handler — Durable
245 * Object classes, a `scheduled` handler — point `main` at your own module
246 * that wraps Astro's handler (imported from
247 * `@alchemy.run/frontend-frameworks/astro/entrypoints/server`) and
248 * re-exports the extras.
249 *
250 * **Example:** Custom entry hosting a Durable Object
251 * ```typescript
252 * // src/worker-entry.ts
253 * // import handler from "@alchemy.run/frontend-frameworks/astro/entrypoints/server";
254 * // export class Counter extends DurableObject { ... }
255 * // export default { ...handler, scheduled: async () => { ... } };
256 *
257 * const site = yield* Cloudflare.Website.Astro("Website", {
258 * main: "src/worker-entry.ts",
259 * env: {
260 * COUNTER: Cloudflare.DurableObject("Counter", {
261 * className: "Counter",
262 * }),
263 * },
264 * });
265 * ```
266 *
267 * ### Custom Rebuild Scope
268 * By default, every non-gitignored file is hashed to decide whether a
269 * rebuild is needed. Use `memo` to narrow the scope when your project
270 * has large directories that don't affect the build output.
271 *
272 * **Example:** Narrowing the memo scope
273 * ```typescript
274 * const site = yield* Cloudflare.Website.Astro("Docs", {
275 * memo: {
276 * include: ["src/**", "public/**", "package.json"],
277 * },
278 * });
279 * ```
280 *
281 * ### Astro Configuration
282 * Your `astro.config.*` is the home for Astro configuration
283 * (integrations, Vite plugins, `site`, `base`, ...) and loads natively.
284 * The Cloudflare adapter is injected for you — declaring an `adapter`
285 * in the config file fails the build. The `astro` prop is a
286 * deploy-time override bag merged OVER the file (values here win) for
287 * settings that vary per stage or derive from other resources'
288 * Outputs, which a config file cannot consume. `output` comes from the
289 * prop, then the config file, then defaults to `"server"` — astro's
290 * zero-config `"static"` default would prerender every page inside
291 * workerd, where the Worker's bindings don't exist.
292 * Use `config` to point at an alternate config file (relative to
293 * `rootDir`).
294 *
295 * **Example:** Per-stage site URL override
296 * ```typescript
297 * const site = yield* Cloudflare.Website.Astro("Blog", {
298 * astro: { site: "https://blog.example.com" },
299 * });
300 * ```
301 *
302 * ### Class Form
303 * Calling `Astro` with no arguments returns a constructor you can
304 * `extend` to declare the Worker as a named class. The class is both an
305 * `Effect` you can `yield*` to deploy and a type you can reference
306 * elsewhere — useful when other resources need to bind to this Worker.
307 *
308 * **Example:** Declaring a Worker class
309 * ```typescript
310 * class Website extends Cloudflare.Website.Astro<Website>()("Website") {}
311 *
312 * const site = yield* Website;
313 * ```
314 *
315 * @resource
316 * @product Website
317 * @category Workers & Compute
318 */
319 export const Astro: {
320 <Self>(): {
321 <const Bindings extends WorkerBindingProps = {}, Req = never>(
322 id: string,
323 propsEff?: AstroInput<Bindings> | Effect.Effect<AstroInput<Bindings>, never, Req>,
324 ): Effect.Effect<Self, never, Req | Providers> & {
325 new (): Worker<{
326 [binding in keyof NormalizedBindings<Bindings, WorkerAssetsConfig>]: NormalizedBindings<
327 Bindings,
328 WorkerAssetsConfig
329 >[binding];
330 }>;
331 };
332 };
333 <const Bindings extends WorkerBindingProps = {}, Req = never>(
334 id: string,
335 propsEff?: AstroInput<Bindings> | Effect.Effect<AstroInput<Bindings>, never, Req>,
336 ): Effect.Effect<
337 Worker<{
338 [binding in keyof NormalizedBindings<Bindings, WorkerAssetsConfig>]: NormalizedBindings<
339 Bindings,
340 WorkerAssetsConfig
341 >[binding];
342 }>,
343 never,
344 Req | Providers
345 >;
346 } = (<const Bindings extends WorkerBindingProps = {}, Req = never>(
347 id?: string,
348 propsEff?: AstroInput<Bindings> | Effect.Effect<AstroInput<Bindings>, never, Req>,
349 ) =>
350 id === undefined
351 ? <const Bindings extends WorkerBindingProps = {}, Req = never>(
352 id: string,
353 propsEff?: AstroInput<Bindings> | Effect.Effect<AstroInput<Bindings>, never, Req>,
354 ) => effectClass(Astro(id, propsEff))
355 : Worker(
356 id,
357 Effect.gen(function* () {
358 const props = (Effect.isEffect(propsEff) ? yield* propsEff : propsEff) ?? {};
359 // The prop wins, then the config file's `output`, then
360 // `"server"`: astro's own zero-config default is `"static"`,
361 // which would prerender every page at build time inside workerd
362 // — where the Worker's bindings don't exist.
363 const { output, workerCache } = yield* resolveAstroSettings({
364 rootDir: props.rootDir,
365 config: props.config,
366 output: props.astro?.output,
367 });
368 const session = props.sessionKVBindingName;
369 const sessionBindingName = typeof session === "string" ? session : "SESSION";
370 let env: WorkerBindingProps | undefined = props.env;
371 // Auto-provision the KV namespace backing Astro's session API
372 // unless the user opted out (`sessionKVBindingName: false`) or
373 // already bound their own namespace under the session name.
374 // An `output: "static"` site is assets-only — no Worker
375 // script runs at request time, so a session namespace could never
376 // be read; skip provisioning it. Resource creation is deduped by
377 // logical id, so re-evaluating this props effect is safe.
378 if (session !== false && output !== "static" && env?.[sessionBindingName] === undefined) {
379 const sessions = yield* Namespace(`${id}Session`);
380 env = { ...env, [sessionBindingName]: sessions };
381 }
382 return {
383 ...props,
384 env,
385 // Astro's Cloudflare cache provider caches responses in Workers
386 // Cache, so turn it on for the Worker unless `cache` is set.
387 cache:
388 props.cache ?? (workerCache && output !== "static" ? { enabled: true } : undefined),
389 // Astro's vendored server runtime is built against Node APIs
390 // and needs `nodejs_compat`; `getCompatibility` already adds it
391 // to every non-python Worker (honoring an explicit
392 // `no_nodejs_compat` opt-out and the v2-mode date guard).
393 main: undefined!,
394 source: {
395 provider: "@alchemy.run/frontend-frameworks/astro/source",
396 devMode: "server",
397 rootDir: props.rootDir,
398 options: {
399 rootDir: props.rootDir,
400 main: props.main,
401 memo: props.memo,
402 // Passed through verbatim (including `false`) so the
403 // source provider can skip its session-driver wiring on
404 // opt-out.
405 sessionKVBindingName: props.sessionKVBindingName,
406 prerenderEnvironment: props.prerenderEnvironment,
407 // The `astro` bag is the deploy-time overlay merged OVER
408 // the natively-loaded `astro.config.*`.
409 astro: { ...props.astro, output },
410 config: props.config,
411 },
412 },
413 };
414 }),
415 )) as any;