Fetch routing API reference

Hinzugefügt in: astro@7.0.0 Beta

The astro/fetch module provides advanced routing handlers built on top of the standard Fetch API.

Imports from astro/fetch

import {
  FetchState,
  astro,
  actions,
  cache,
  i18n,
  middleware,
  pages,
  redirects,
  sessions,
  trailingSlash,
} from "astro/fetch";

FetchState

The per-request state object. Create one at the start of your fetch method:

import { FetchState } from 'astro/fetch';

const state = new FetchState(request);

FetchState tracks the matched route, cookies, session providers, and other per-request data. All handler functions require it as their first argument.

Learn how to compose handlers with FetchState in the advanced routing guide.

Properties

state.request

Type: Request

The incoming Request object.

state.url

Type: URL

A normalized URL derived from the request.

state.pathname

Type: string

The base-stripped, decoded pathname of the request (e.g. /about or /blog/my-post).

state.routeData

Type: RouteData | undefined

The matched route for this request, if any. This is resolved automatically when the FetchState is created.

state.cookies

Type: AstroCookies

An AstroCookies instance for reading and setting cookies on this request.

state.locals

Type: App.Locals

A request-scoped object for storing custom data. This is the same locals object available in middleware and API routes.

state.params

Type: Params | undefined

Route parameters derived from the matched route and pathname (e.g. { slug: 'my-post' } for a [slug].astro route).

state.status

Type: number
Default: 200

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() and middleware(), allowing you to inspect or use the response later in the pipeline:

const response = await middleware(state, (s) => pages(s));
// state.response is now the same object as response

Methods

state.rewrite()

Type: (payload: RewritePayload) => Promise<Response>

Triggers a rewrite to a different route. The payload can be a pathname string ('/other-page'), a URL, or a Request:

const response = await state.rewrite('/other-page');

astro()

Type: (state: FetchState) => Promise<Response>

The all-in-one handler that runs the full Astro pipeline (sessions, cache, redirects, trailing-slash, actions, middleware, pages, and i18n) in the default order. Use this when you want to add logic before or after Astro without changing the internal pipeline order:

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 here...
    const response = await astro(state);
    // custom post-processing here...
    return response;
  },
};

actions()

Type: (state: FetchState) => Promise<Response | undefined> | undefined

Handles Astro Actions (RPC and form submissions). Returns a Response for RPC actions, or undefined for form actions and non-action requests. Check the return value to decide whether to continue rendering:

const actionResponse = await actions(state);
if (actionResponse) return actionResponse;
// otherwise continue to page rendering...

cache()

Type: (state: FetchState, next: () => Promise<Response>) => Promise<Response>

Wraps a render callback with cache provider logic. Handles runtime caching, CDN-based providers, and the no-cache case.

i18n()

Type: (state: FetchState, response: Response) => Promise<Response>

Post-processes a response against your i18n configuration. Handles locale redirects, 404s for invalid locales, and fallback routing. Call this after rendering:

const response = await middleware(state, (s) => pages(s));
return i18n(state, response);

middleware()

Type: (state: FetchState, next: (state: FetchState) => Promise<Response>) => Promise<Response>

Runs Astro’s middleware chain (from src/middleware.ts). The next callback is called at the bottom of the chain to produce the response, typically by calling pages():

const response = await middleware(state, (s) => pages(s));

pages()

Type: (state: FetchState) => Promise<Response>

Dispatches the request to the matched Astro route (page, endpoint, or fallback). This is the core rendering handler, and most custom pipelines will include it.

redirects()

Type: (state: FetchState) => Promise<Response> | undefined

Handles redirect routes defined in your Astro config. Returns a redirect Response if the matched route is a redirect, or undefined if the caller should continue processing.

sessions()

Type: (state: FetchState) => Promise<void> | void

Registers the session provider. Sessions are created lazily when your code accesses ctx.session and persisted automatically at the end of the request. Call this early in the pipeline (before middleware runs):

await sessions(state);
// ...render pipeline...

trailingSlash()

Type: (state: FetchState) => Response | undefined

Checks if the request pathname needs trailing-slash normalization and returns a redirect Response if so. Returns undefined when no redirect is needed.