diff --git a/src/content/docs/en/reference/experimental-flags/advanced-routing.mdx b/src/content/docs/en/reference/experimental-flags/advanced-routing.mdx index 2f4deb47b0ed0..b3cc1b1eb4e4c 100644 --- a/src/content/docs/en/reference/experimental-flags/advanced-routing.mdx +++ b/src/content/docs/en/reference/experimental-flags/advanced-routing.mdx @@ -477,3 +477,53 @@ export default app; ``` The `astro/hono` module exports the same handler names as `astro/fetch` (`astro`, `pages`, `middleware`, `actions`, `sessions`, `redirects`, `cache`, `i18n`, `trailingSlash`), but each returns a Hono middleware function. This lets you mix Astro handlers with any Hono middleware from the ecosystem. + +## Cloudflare adapter + +The [`@astrojs/cloudflare`](/en/guides/integrations-guide/cloudflare/) adapter provides companion handlers that apply Cloudflare-specific setup to your advanced routing pipeline. These handlers configure session KV binding injection, static asset serving via the `ASSETS` binding, `Astro.locals.cfContext`, client address from the `cf-connecting-ip` header, `waitUntil`, and prerendered error page fetching. + +You can use the `astro/fetch` and `astro/hono` APIs from `src/app.ts` on Cloudflare without these handlers. The adapter's default entrypoint takes care of Cloudflare-specific setup for you. These companion handlers are useful when you already have a [custom worker entrypoint](https://developers.cloudflare.com/workers/wrangler/configuration/#inheritable-keys) (`src/worker.ts`), for example, to export a Durable Object, and want to use the advanced routing APIs directly from that file instead. + +When using these handlers in your worker entrypoint, they replace the functionality of the adapter's default handler, so you should not use both at the same time. Place the Cloudflare handler before other Astro handlers so that bindings and locals are available to the rest of the pipeline. + +### `@astrojs/cloudflare/fetch` + +

+ +For use with `astro/fetch`. The `cf()` function receives a `FetchState`, the Cloudflare `env`, and the `ExecutionContext`. It returns a `Response` for static asset hits, or `undefined` when the request should continue to Astro rendering: + +```ts title="src/worker.ts" +import { astro, FetchState } from 'astro/fetch'; +import { cf } from '@astrojs/cloudflare/fetch'; + +export default { + async fetch(request: Request, env: Env, ctx: ExecutionContext) { + const state = new FetchState(request); + const asset = await cf(state, env, ctx); + if (asset) return asset; + return astro(state); + }, +}; +``` + +### `@astrojs/cloudflare/hono` + +

+ +For use with `astro/hono`. The `cf()` function returns a Hono middleware that reads `env` and `executionCtx` from the Hono context automatically: + +```ts title="src/worker.ts" +import { Hono } from 'hono'; +import { actions, middleware, pages, i18n } from 'astro/hono'; +import { cf } from '@astrojs/cloudflare/hono'; + +const app = new Hono<{ Bindings: Env }>(); + +app.use(cf()); +app.use(actions()); +app.use(middleware()); +app.use(pages()); +app.use(i18n()); + +export default app; +```