From 6ef6269dd430b0a0c3b3e4bb41fe0c5dca78b40d Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Tue, 19 May 2026 09:44:23 -0400 Subject: [PATCH 1/7] Add Cloudflare adapter section to advanced routing docs --- .../experimental-flags/advanced-routing.mdx | 44 +++++++++++++++++++ 1 file changed, 44 insertions(+) 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..a929dcefae67a 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,47 @@ 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. + +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/app.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/app.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; +``` From 392f0aaa0e88afcc9f9fc536291c99feba453c81 Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Tue, 19 May 2026 09:47:18 -0400 Subject: [PATCH 2/7] Add Since tags for @astrojs/cloudflare 13.6.0 --- .../docs/en/reference/experimental-flags/advanced-routing.mdx | 4 ++++ 1 file changed, 4 insertions(+) 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 a929dcefae67a..5e96dd5e45dcd 100644 --- a/src/content/docs/en/reference/experimental-flags/advanced-routing.mdx +++ b/src/content/docs/en/reference/experimental-flags/advanced-routing.mdx @@ -486,6 +486,8 @@ Place the Cloudflare handler before other Astro handlers so that bindings and lo ### `@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/app.ts" @@ -504,6 +506,8 @@ export default { ### `@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/app.ts" From 8f90f7695b6652d14c08fc931bfae30576fe867c Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Tue, 19 May 2026 11:49:22 -0400 Subject: [PATCH 3/7] Clarify relationship with wrangler.jsonc main and default handler --- .../en/reference/experimental-flags/advanced-routing.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) 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 5e96dd5e45dcd..9f18932f5e9a3 100644 --- a/src/content/docs/en/reference/experimental-flags/advanced-routing.mdx +++ b/src/content/docs/en/reference/experimental-flags/advanced-routing.mdx @@ -482,6 +482,8 @@ The `astro/hono` module exports the same handler names as `astro/fetch` (`astro` 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. +These handlers replace the functionality of the adapter's default entrypoint (`@astrojs/cloudflare/utils/handler`). When using them, point `main` in your `wrangler.jsonc` to your own entrypoint file instead of the default handler. Do 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` @@ -490,7 +492,7 @@ Place the Cloudflare handler before other Astro handlers so that bindings and lo 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/app.ts" +```ts title="src/worker.ts" import { astro, FetchState } from 'astro/fetch'; import { cf } from '@astrojs/cloudflare/fetch'; @@ -510,7 +512,7 @@ export default { 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/app.ts" +```ts title="src/worker.ts" import { Hono } from 'hono'; import { actions, middleware, pages, i18n } from 'astro/hono'; import { cf } from '@astrojs/cloudflare/hono'; From be1c59fa916abfb869e7a6298e5b1a8a2e9e1c1b Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Tue, 19 May 2026 13:15:06 -0400 Subject: [PATCH 4/7] Update src/content/docs/en/reference/experimental-flags/advanced-routing.mdx Co-authored-by: Armand Philippot --- .../docs/en/reference/experimental-flags/advanced-routing.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 9f18932f5e9a3..64e26eb43a3b5 100644 --- a/src/content/docs/en/reference/experimental-flags/advanced-routing.mdx +++ b/src/content/docs/en/reference/experimental-flags/advanced-routing.mdx @@ -508,7 +508,7 @@ export default { ### `@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: From cbb67d6d0df1faeb2180df8e9a35325578d72374 Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Tue, 19 May 2026 15:26:05 -0400 Subject: [PATCH 5/7] Rework Cloudflare section: clarify when to use companion handlers vs app.ts --- .../en/reference/experimental-flags/advanced-routing.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) 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 64e26eb43a3b5..e4db2e3652eb8 100644 --- a/src/content/docs/en/reference/experimental-flags/advanced-routing.mdx +++ b/src/content/docs/en/reference/experimental-flags/advanced-routing.mdx @@ -482,13 +482,13 @@ The `astro/hono` module exports the same handler names as `astro/fetch` (`astro` 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. -These handlers replace the functionality of the adapter's default entrypoint (`@astrojs/cloudflare/utils/handler`). When using them, point `main` in your `wrangler.jsonc` to your own entrypoint file instead of the default handler. Do not use both at the same time. +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/runtime-apis/handlers/fetch/) (`src/worker.ts`), for example to export a Durable Object, and want to use the advanced routing APIs directly from that file instead. -Place the Cloudflare handler before other Astro handlers so that bindings and locals are available to the rest of the pipeline. +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: From 90f54607025f7cf917988a894f87d5ca5f79f953 Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Wed, 20 May 2026 09:50:28 -0400 Subject: [PATCH 6/7] Update src/content/docs/en/reference/experimental-flags/advanced-routing.mdx Co-authored-by: Yan <61414485+yanthomasdev@users.noreply.github.com> --- .../docs/en/reference/experimental-flags/advanced-routing.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 e4db2e3652eb8..0746d76c91a51 100644 --- a/src/content/docs/en/reference/experimental-flags/advanced-routing.mdx +++ b/src/content/docs/en/reference/experimental-flags/advanced-routing.mdx @@ -482,7 +482,7 @@ The `astro/hono` module exports the same handler names as `astro/fetch` (`astro` 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/runtime-apis/handlers/fetch/) (`src/worker.ts`), for example to export a Durable Object, and want to use the advanced routing APIs directly from that file instead. +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/runtime-apis/handlers/fetch/) (`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. From 79586ef36c98ef5a959c2848fc0c0be37aa4cbf9 Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Wed, 20 May 2026 11:40:40 -0400 Subject: [PATCH 7/7] Fix Cloudflare custom worker entrypoint link to Wrangler config docs --- .../docs/en/reference/experimental-flags/advanced-routing.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 0746d76c91a51..b3cc1b1eb4e4c 100644 --- a/src/content/docs/en/reference/experimental-flags/advanced-routing.mdx +++ b/src/content/docs/en/reference/experimental-flags/advanced-routing.mdx @@ -482,7 +482,7 @@ The `astro/hono` module exports the same handler names as `astro/fetch` (`astro` 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/runtime-apis/handlers/fetch/) (`src/worker.ts`), for example, to export a Durable Object, and want to use the advanced routing APIs directly from that file instead. +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.