Routing

Astro's routing is filesystem-based. Files under src/pages/ become routes; the framework discovers them once at build/dev start, sorts them by priority, and then matches incoming requests.

Purpose

Translate a project's src/pages/, redirects config, and prerender flags into a RouteData[] manifest. Match each request against that manifest and produce the route plus URL params.

Key files

File	Purpose
packages/astro/src/core/routing/router.ts	createRouteManifest() — walks src/pages/.
packages/astro/src/core/routing/match.ts	matchRoute() for a given URL.
packages/astro/src/core/routing/parse-route.ts	Lowers [slug]/[...rest].astro into a regex + segment list.
packages/astro/src/core/routing/parts.ts, segment.ts	Atomic route segment representations.
packages/astro/src/core/routing/pattern.ts	Compiles segments to a RegExp.
packages/astro/src/core/routing/priority.ts	Sorts overlapping dynamic routes.
packages/astro/src/core/routing/params.ts	Extracts dynamic params from a URL.
packages/astro/src/core/routing/prerender.ts	Determines whether a route prerenders or runs at request time.
packages/astro/src/core/routing/redirects/	Computes redirect routes from config.
packages/astro/src/core/routing/3xx.ts	3xx response builders (redirects, rewrites).
packages/astro/src/core/routing/rewrite.ts	The Astro.rewrite() runtime.
packages/astro/src/core/routing/validation.ts	getStaticPaths validation.
packages/astro/src/core/routing/dev.ts	Dev-server-specific helpers (matching with stale module tracking).
packages/astro/src/core/routing/generator.ts	URL generators for use in getStaticPaths results.
packages/astro/src/core/routing/astro-designed-error-pages.ts	The fallback 404/500 mechanism.

Manifest construction

graph LR
    A[src/pages/ scan] --> B[parse-route]
    B --> C[segment + pattern]
    C --> D[priority sort]
    E[redirects config] --> D
    F[404/500 fallbacks] --> D
    D --> G[RouteData manifest]

createRouteManifest() runs once per dev session and once per build. It produces RouteData objects whose shape is exposed publicly via astro/types.

Matching

graph TD
    A[Request URL] --> B[Decode + normalize]
    B --> C[matchRoute against manifest]
    C --> D{Match?}
    D -- yes --> E[Extract params]
    E --> F[Hand off to RenderContext]
    D -- no --> G[Try fallback i18n route]
    G --> H{Match?}
    H -- yes --> F
    H -- no --> I[Designed 404]

The matcher walks the priority-sorted manifest. Catch-all routes ([...rest].astro) sit at the bottom; static routes win. Dynamic routes' regexes are pre-compiled.

Static paths

For prerendered dynamic routes (getStaticPaths), the routing layer asks the page module for the list of params/props at build time, validates them with validation.ts, and emits one HTML file per result. Caching is in packages/astro/src/core/render/route-cache.ts. Recent change: feat: route caching (commit 08437d5) added cache reuse during long-running production servers.

Redirects and rewrites

• Redirects — declared via astro.config.mjs's redirects map. The router converts them into terminal RouteData entries that respond with a 3xx.
• Rewrites — the page or middleware calls Astro.rewrite() which re-runs matchRoute against the new URL with the same RenderContext. Source: core/routing/rewrite.ts.

i18n integration

packages/astro/src/i18n/router.ts and packages/astro/src/i18n/middleware.ts wrap the route matcher. They prepend a locale prefix, fall back to a configured default locale, and emit per-locale RouteData clones. See features / i18n.

Public types

astro/types/RouteData, astro/types/RouteType, and helpers on Astro.routes (the astro:routes:resolved event) expose the manifest to integrations.

Entry points for modification

• Change how files become routes: core/routing/router.ts (be aware that vite-plugin-pages and vite-plugin-routes re-discover routes during HMR).
• Add a redirect form: core/routing/redirects/.
• Add a new param syntax: core/routing/parse-route.ts and parts.ts.

Related pages

• systems / render context
• systems / build pipeline
• features / i18n