File-Based Routing

Astro doesn't use a routing library or a route configuration file. Instead, the file structure under src/pages/ is the route structure — a convention borrowed from frameworks like Next.js, and one that removes an entire category of configuration from a project.

Files become routes

src/pages/
├── index.astro          →  /
├── about.astro           →  /about
├── contact.astro         →  /contact
└── blog/
    ├── index.astro        →  /blog
    └── first-post.astro   →  /blog/first-post

An index.astro file maps to the directory it's in, not to a route literally named "index" — so src/pages/index.astro is the site root, and src/pages/blog/index.astro is /blog. Any other filename becomes a route segment with that exact name.

Nesting mirrors URL structure

Because folders map to URL segments, organizing routes is just organizing files:

src/pages/
└── docs/
    ├── getting-started.astro   →  /docs/getting-started
    └── guides/
        └── deployment.astro    →  /docs/guides/deployment

There's no separate step to "register" /docs/guides/deployment — creating the file at that path is the registration. Renaming or moving the file changes the route immediately, which also means route structure is discoverable just by browsing the project in an editor's file tree, without cross-referencing a router config.

.astro isn't the only option

Pages can also be .md, .mdx (with the MDX integration), or .js/.ts files that export an HTTP handler — useful for API endpoints:

// src/pages/api/hello.js
export function GET() {
  return new Response(JSON.stringify({ message: "Hello from Astro" }), {
    headers: { "Content-Type": "application/json" },
  });
}

This file becomes a real endpoint at /api/hello that returns JSON instead of HTML — the same file-based convention extends to APIs, not just pages.

What routing doesn't need configuring

There's no <Route path="..." component={...} /> list, no route array, and no client-side router shipped to the browser for these routes — navigating between pages is a normal full page load (Astro can optionally enable view transitions for smoother navigation, but that's opt-in, not the default). This is consistent with Astro's overall philosophy: the simplest, most static option is the default, and you reach for more machinery — dynamic routes, API endpoints, client-side navigation — only when a page actually needs it. The next lesson covers dynamic routes, where a single file generates many pages from data.