Routing in Astro

This chapter follows Astro components.

Astro has no router configuration file. The folder structure under src/pages/ is the route table, and each request loads a full HTML page. That makes Astro a multi-page application by default; client-side navigation is an optional layer on top, covered in Islands and client directives.

File-based routes

Every .astro, .md, .mdx, .html, .js, or .ts file in src/pages/ becomes a route:

Files and folders that start with an underscore (_draft.astro, _components/) are ignored, which lets you keep helpers next to the pages that use them. Link between pages with ordinary <a href> elements; there is no special link component.

Dynamic routes

Brackets in a file or folder name create a parameter. For a static build, Astro must know every value in advance, so the page exports getStaticPaths():

1
---
2
import type { GetStaticPaths } from 'astro';
3

4
export const getStaticPaths = (() => {
5
  return [
6
    { params: { tag: 'astro' }, props: { label: 'Astro' } },
7
    { params: { tag: 'routing' }, props: { label: 'Routing' } },
8
  ];
9
}) satisfies GetStaticPaths;
10

11
const { tag } = Astro.params;
12
const { label } = Astro.props;
13
---
14
<h1>Articles tagged {label}</h1>
15
<p>URL parameter: {tag}</p>

getStaticPaths runs once at build time. Each returned object produces one HTML file. params fills the brackets; props passes data straight to that page so you do not have to look it up again. A route can combine several parameters, such as src/pages/[lang]/[slug].astro.

Rest parameters

[...path] matches any depth, including none:

1
---
2
export function getStaticPaths() {
3
  return [
4
    { params: { path: undefined } },
5
    { params: { path: 'install' } },
6
    { params: { path: 'guides/routing' } },
7
  ];
8
}
9
const { path } = Astro.params;
10
---
11
<h1>Docs: {path ?? 'home'}</h1>

This produces /docs/, /docs/install/, and /docs/guides/routing/. This knowledgebase uses nested dynamic folders ([domain]/[area]/[topic]/[slug].astro) to turn each article’s frontmatter into its URL.

Route priority

When several routes could match one URL, Astro picks the most specific. In short: static segments beat dynamic ones, named parameters beat rest parameters, and routes with more segments beat shorter ones. Endpoints and pages follow the same rules.

flowchart LR
  url["/posts/create"] --> a["posts/create.astro - wins"]
  url -.-> b["posts/[id].astro"]
  url -.-> c["posts/[...slug].astro"]

When two routes are equally specific and would build the same URL, Astro reports a collision instead of guessing.

Endpoints

A .ts or .js file in src/pages/ that exports HTTP method handlers is an endpoint. In a static build it generates a file; with on-demand rendering it runs per request.

1
import type { APIRoute } from 'astro';
2

3
const articles = [
4
  { slug: 'routing-in-astro', title: 'Routing in Astro' },
5
  { slug: 'astro-components', title: 'Astro components' },
6
];
7

8
export const GET: APIRoute = () => {
9
  return new Response(JSON.stringify(articles), {
10
    headers: { 'Content-Type': 'application/json' },
11
  });
12
};

Endpoints return a standard Response. Use them for JSON, RSS feeds, robots.txt, sitemaps, or generated images. Dynamic endpoints use getStaticPaths exactly like pages.

Redirects and error pages

Permanent moves belong in the config, so they apply in both static and server output:

1
import { defineConfig } from 'astro/config';
2

3
export default defineConfig({
4
  redirects: {
5
    '/old-post/': '/blog/new-post/',
6
    '/blog/[slug]/': '/articles/[slug]/',
7
  },
8
});

For a static site Astro writes a small HTML file with a meta refresh at the old URL; hosts with an adapter can turn redirects into real HTTP status codes. Inside an on-demand page, return Astro.redirect('/login/') redirects per request.

src/pages/404.astro becomes the not-found page. With on-demand rendering, src/pages/500.astro handles server errors.

Trailing slashes and build format

trailingSlash in the config decides whether /about and /about/ are the same URL: 'always', 'never', or 'ignore'. Pick one and keep links consistent; it affects canonical URLs and how static hosts resolve files. build.format controls whether about.astro becomes about/index.html ('directory', the default) or about.html ('file').

Next: Content collections in Astro.