feat(v7): stabilize advanced routing (#13983)

Co-authored-by: Matthew Phillips <matthewphillips@cloudflare.com>

Author: ArmandPhilippot

astro.sidebar.ts

@@ -131,6 +131,8 @@ export const sidebar = [
 					'reference/modules/astro-config',
 					'reference/modules/astro-content',
 					'reference/modules/astro-env',
+					'reference/modules/astro-fetch',
+					'reference/modules/astro-hono',
 					'reference/modules/astro-i18n',
 					'reference/modules/astro-middleware',
 					'reference/modules/astro-static-paths',
@@ -161,7 +163,6 @@ export const sidebar = [
 					'reference/experimental-flags/content-intellisense',
 					'reference/experimental-flags/chrome-devtools-workspace',
 					'reference/experimental-flags/svg-optimization',
-					'reference/experimental-flags/advanced-routing',
 				],
 			}),
 			'reference/legacy-flags',

public/_redirects

@@ -53,6 +53,7 @@
 /:lang/reference/experimental-flags/live-content-collections/    /:lang/guides/content-collections/#live-content-collections
 /:lang/reference/experimental-flags/preserve-scripts-order/      /:lang/guides/client-side-scripts/
 /:lang/reference/experimental-flags/static-import-meta-env/      /:lang/guides/environment-variables/
+/:lang/reference/experimental-flags/advanced-routing/            /:lang/guides/routing/
 
 # Very old docs site redirects
 # Once upon a time these URLs existed, so we try to keep them meaning something.

src/content/docs/en/guides/integrations-guide/cloudflare.mdx

@@ -428,6 +428,58 @@ export default defineConfig({
 });
 ```
 
+## Using advanced routing
+
+<p><Since v="13.6.0" pkg="@astrojs/cloudflare" /></p>
+
+The Cloudflare adapter provides companion handlers that apply Cloudflare-specific setup to your [advanced routing pipeline](/en/guides/routing/#advanced-routing). 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`](/en/reference/modules/astro-fetch/) and [`astro/hono`](/en/reference/modules/astro-hono/) APIs from `src/fetch.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.
+
+### With the Fetch API
+
+<p><Since v="13.6.0" pkg="@astrojs/cloudflare" /></p>
+
+For use with [`astro/fetch`](/en/reference/modules/astro-fetch/). The `cf()` function imported from `@astrojs/cloudflare/fetch` receives a [`FetchState`](/en/reference/modules/astro-fetch/#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);
+  },
+};
+```
+
+### With Hono
+
+<p><Since v="13.6.0" pkg="@astrojs/cloudflare" /></p>
+
+For use with [`astro/hono`](/en/reference/modules/astro-hono/). The `cf()` function imported from `@astrojs/cloudflare/hono` 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;
+```
+
 ## Upgrading to v13 and Astro 6
 
 Astro 6 brings significant improvements to the Cloudflare development experience and requires `@astrojs/cloudflare` v13 or later. Now, `astro dev` uses Cloudflare's Vite plugin and `workerd` runtime to closely mirror production behavior.

src/content/docs/en/guides/routing.mdx

@@ -575,3 +575,149 @@ In this example, only `src/pages/index.astro` and `src/pages/projects/project1.m
     - _utils.js
     - **project1.md**
 </FileTree>
+
+## Advanced routing
+
+<p><Since v="7.0.0" /></p>
+
+By default, Astro handles every request with a built-in pipeline that runs the handlers in a fixed order: trailing-slash normalization, redirects, sessions, actions, user middleware, page rendering, i18n, and caching. This pipeline is designed to cover the most common use cases for routing and request handling, but it may not fit every project’s needs.
+
+Astro's advanced routing allows you to replace this pipeline with your own. You can choose which built-in features to use and where to use them. You can also add your own custom logic anywhere in the pipeline. This gives you full control over how Astro handles incoming requests.
+
+### Creating a custom entrypoint
+
+When the default pipeline does not fit your needs, you can override it by creating a `src/fetch.ts` file that default-exports an object with a `fetch()` method. This method receives a standard [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) and must return a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response).
+
+```ts title="src/fetch.ts"
+import type { Fetchable } from 'astro';
+
+export default {
+  async fetch(request) {
+    // Your custom request handling logic here
+    return new Response("Hello from advanced routing!");
+  }
+} satisfies Fetchable;
+```
+
+Astro supports several file formats for its advanced routing entrypoint: `.ts`, `.js`, `.mjs`, and `.mts`. We recommend using `.js` in most cases or `.ts` if you need TypeScript support.
+
+### Changing the entrypoint filename
+
+By default, Astro looks for `src/fetch.ts` as the advanced routing entrypoint. You can change this by setting the `fetchFile` option in your Astro config file.
+
+The following example tells Astro to look for `src/handler.ts` instead of `src/fetch.ts`:
+
+```js title="astro.config.mjs"
+export default defineConfig({
+  fetchFile: 'handler',
+});
+```
+
+Set `fetchFile` to `null` to disable the entrypoint entirely. This is useful if you already have a `src/fetch.ts` file used for other purposes:
+
+```js title="astro.config.mjs"
+export default defineConfig({
+  experimental: {
+    advancedRouting: {
+      fetchFile: null,
+    },
+  },
+});
+```
+
+### Adding custom logic
+
+The main benefit of advanced routing is the ability to insert custom logic into the request pipeline. You can run code before Astro touches the request, between pipeline stages, or after the response is produced.
+
+You can do this in two ways:
+
+- Use the [`astro()` handler](/en/reference/modules/astro-fetch/#astro) to run the full built-in pipeline, and add logic before or after it.
+- Compose individual handlers from [`astro/fetch`](/en/reference/modules/astro-fetch/) or [`astro/hono`](/en/reference/modules/astro-hono/) for more control over execution order.
+
+#### Running the full pipeline with `astro()`
+
+Use [`astro()`](/en/reference/modules/astro-fetch/#astro) when you want to keep Astro's built-in routing behavior, but need custom logic around it. This approach preserves the default pipeline order and lets you add pre-processing and post-processing in one place. For many use cases, such as adding auth guards, request logging, and custom headers, `astro()` is all you need.
+
+The following example checks if a user can access a dashboard before running the Astro pipeline, and adds a custom header to the response once Astro has finished running:
+
+```ts title="src/fetch.ts"
+import { FetchState, astro } from 'astro/fetch';
+
+export default {
+  async fetch(request: Request): Promise<Response> {
+    const state = new FetchState(request);
+
+    // Custom pre-processing, runs before any Astro handler
+    const url = new URL(request.url);
+    if (url.pathname.startsWith('/dashboard')) {
+      const cookie = request.headers.get('cookie') ?? '';
+      if (!cookie.includes('session=')) {
+        return new Response(null, {
+          status: 302,
+          headers: { Location: '/login' },
+        });
+      }
+    }
+
+    const response = await astro(state);
+
+    // Custom post-processing, runs after Astro renders
+    response.headers.set('X-Powered-By', 'Astro');
+    return response;
+  },
+};
+```
+
+#### Composing individual handlers
+
+When you need more control over the pipeline execution order, or want to omit certain features, you can compose individual handler functions from [`astro/fetch`](/en/reference/modules/astro-fetch/). Each handler operates on a [`FetchState` object](/en/reference/modules/astro-fetch/#fetchstate) that tracks per-request data, such as the matched route, cookies, and session. You can call handlers in any order and insert custom logic between stages.
+
+The following example runs only the handlers used in the project and adds custom logic after actions and before page rendering:
+
+```ts title="src/fetch.ts"
+import {
+  FetchState,
+  actions,
+  middleware,
+  pages,
+  i18n,
+} from 'astro/fetch';
+
+export default {
+  async fetch(request: Request): Promise<Response> {
+    const state = new FetchState(request);
+
+    const actionResponse = await actions(state);
+    if (actionResponse) return actionResponse;
+
+    // Custom logic between actions and page rendering
+    console.log(`Rendering ${new URL(request.url).pathname}`);
+
+    const response = await middleware(state, (s) => pages(s));
+    return i18n(state, response);
+  },
+};
+```
+
+### Using with Hono
+
+Astro also provides Hono-compatible wrappers for all handler functions via [`astro/hono`](/en/reference/modules/astro-hono/). If you prefer to use [Hono](https://hono.dev/) as your routing framework, you can export a Hono app from `src/fetch.ts`:
+
+```ts title="src/fetch.ts"
+import { Hono } from 'hono';
+import { logger } from 'hono/logger';
+import { actions, middleware, pages, i18n } from 'astro/hono';
+
+const app = new Hono();
+
+// Hono middleware
+app.use(logger());
+
+// Astro handlers (as Hono middleware)
+app.use(actions());
+app.use(middleware());
+app.use(pages());
+app.use(i18n());
+
+export default app;
+```

src/content/docs/en/guides/upgrade-to/v7.mdx

@@ -93,6 +93,7 @@ export default defineConfig({
       enabled: true,
     },
     rustCompiler: true,
+    advancedRouting: true,
   },
 });
 ```
@@ -103,6 +104,33 @@ export default defineConfig({
 
 - `rustCompiler`: The Rust-based Astro compiler is now the default and only compiler, replacing the previous Go-based compiler. No action is required for most projects. If you encounter any issues, please report them on [GitHub](https://github.com/withastro/astro/issues).
 
+- `advancedRouting`: Advanced routing is now enabled by default. See the [advanced routing guide](/en/guides/routing/#advanced-routing) for more information. Note that `src/fetch.ts` is now a [reserved file name](#reserved-file-name-srcfetchts).
+
+### Reserved file name: `src/fetch.ts`
+
+Astro v7.0 introduces [advanced routing](/en/guides/routing/#advanced-routing), which uses `src/fetch.ts` (or `src/fetch.js`) as a special file name, similar to `src/middleware.ts`. Astro will automatically import this file to configure routing behavior.
+
+If your project already has a `src/fetch.ts` file used for other purposes, Astro will attempt to process it as an advanced routing configuration, which may cause unexpected errors.
+
+#### What should I do?
+
+If you have an existing `src/fetch.ts` file that is not related to advanced routing, you have two options:
+
+* **Configure `fetchFile`**: you can specify a different filename or `null` to disable advanced routing. This is useful if you want to keep using `src/fetch.ts` for another purpose, or don't need advanced routing features:
+
+    ```js title="astro.config.mjs" ins={5}
+    import { defineConfig } from 'astro/config';
+
+    export default defineConfig({
+      // specify a different file for advanced routing configuration:
+      fetchFile: './src/router.ts',
+      // or disable advanced routing entirely:
+      // fetchFile: null,
+    });
+    ```
+
+* **Rename your file** to something else (e.g. `src/fetcher.ts`, `src/main.ts`), and update any imports that reference it.
+
 ## Removed
 
 The following features have now been entirely removed from the code base and can no longer be used. Some of these features may have continued to work in your project even after deprecation. Others may have silently had no effect.