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 02e76723009ea..2f4deb47b0ed0 100644 --- a/src/content/docs/en/reference/experimental-flags/advanced-routing.mdx +++ b/src/content/docs/en/reference/experimental-flags/advanced-routing.mdx @@ -34,6 +34,46 @@ When `advancedRouting` is enabled, create a `src/app.ts` (or `.js`, `.mjs`, `.mt If no `src/app.ts` file exists (or `advancedRouting` is not enabled), Astro uses its built-in pipeline, which runs all features automatically. +You can optionally import the `Fetchable` type from `astro` to type-check your entrypoint: + +```ts title="src/app.ts" +import type { Fetchable } from 'astro'; + +export default { + async fetch(request: Request): Promise { + // ... + }, +} satisfies Fetchable; +``` + +### Customizing the entrypoint file + +By default, Astro looks for `src/app.ts` as the advanced routing entrypoint. Pass an object to `advancedRouting` with a `fetchFile` option to use a different file: + +```js title="astro.config.mjs" +export default defineConfig({ + experimental: { + advancedRouting: { + fetchFile: 'fetch.ts', + }, + }, +}); +``` + +With this configuration, Astro will look for `src/fetch.ts` instead of `src/app.ts`. + +Set `fetchFile` to `null` to disable the entrypoint entirely. This is useful if you already have a `src/app.ts` file used for other purposes: + +```js title="astro.config.mjs" +export default defineConfig({ + experimental: { + advancedRouting: { + fetchFile: null, + }, + }, +}); +``` + ### Using `astro()` The easiest way to get started is with the [`astro()` handler](#astro), which runs Astro's full built-in pipeline (sessions, cache, redirects, trailing-slash, actions, middleware, pages, and i18n) in the default order. This lets you add custom logic before or after Astro without changing how the internal pipeline works: @@ -132,6 +172,20 @@ export default { }; ``` +## Typing custom providers with `App.Providers` + +When you register custom context providers with [`state.provide()`](#stateprovide), you can declare their types using the `App.Providers` interface so that `Astro` and `ctx` are fully typed in your components and middleware: + +```ts title="src/env.d.ts" +declare namespace App { + interface Providers { + oauth: import('./lib/oauth').OAuthSession; + } +} +``` + +After declaring a provider, `ctx.oauth` (and `Astro.oauth` in `.astro` files) will be typed automatically. + ## `astro/fetch` handler reference All handler functions are imported from `astro/fetch` and operate on a `FetchState` object. @@ -202,6 +256,21 @@ Route parameters derived from the matched route and pathname (e.g. `{ slug: 'my- The HTTP status code for the response. You can set this before rendering to control the response status (e.g. `state.status = 404`). +##### `state.response` + +

+ +**Type:** `Response | undefined`
+**Default:** `undefined` +

+ +The `Response` produced by handlers after rendering completes. This is set automatically by [`pages()`](#pages) and [`middleware()`](#middleware), allowing you to inspect or use the response later in the pipeline: + +```ts +const response = await middleware(state, (s) => pages(s)); +// state.response is now the same object as response +``` + #### Methods ##### `state.rewrite()`