Astro Routing Pattern

File-based routing maps your

src/pages/

directory structure to URLs — static, dynamic, and rest-parameter routes all follow the same filesystem convention.

When to Use

• You are creating new pages or routes in an Astro project
• You need dynamic routes (e.g.,

  /blog/[slug]

  ) and must implement

  getStaticPaths()

• You want to use rest parameters for catch-all or paginated routes
• You are configuring redirects, custom 404 pages, or route priority
• You are moving from SSG to SSR and need to understand which routing behaviors change

Instructions

1. Create files in

   src/pages/

   to define routes. The file path maps directly to the URL:

   • src/pages/index.astro

     →

     /

   • src/pages/about.astro

     →

     /about

   • src/pages/blog/index.astro

     →

     /blog

   • src/pages/blog/first-post.astro

     →

     /blog/first-post

2. Use bracket syntax for dynamic route segments. The bracket name becomes the param key:

   • src/pages/blog/[slug].astro

     →

     /blog/:slug

   • src/pages/[lang]/about.astro

     →

     /:lang/about

3. Implement

   getStaticPaths()

   in every dynamic route page used in SSG mode. It must return an array of

   { params }

   objects:

---
// src/pages/blog/[slug].astro
import { getCollection } from 'astro:content';

export async function getStaticPaths() {
  const posts = await getCollection('blog');
  return posts.map((post) => ({
    params: { slug: post.slug },
    props: { post },          // pass data to avoid re-fetching in frontmatter
  }));
}

const { post } = Astro.props;
const { Content } = await post.render();
---
<article>
  <h1>{post.data.title}</h1>
  <Content />
</article>

4. Use rest parameters (

   [...slug]

   ) for nested dynamic routes and catch-all paths:

   • src/pages/docs/[...slug].astro

     matches

     /docs/

     ,

     /docs/guide

     ,

     /docs/guide/intro

   • Access via

     Astro.params.slug

     — it will be

     undefined

     (root),

     'guide'

     , or

     'guide/intro'

5. Implement pagination with

   paginate()

   inside

   getStaticPaths()

   :

export async function getStaticPaths({ paginate }) {
  const posts = await getCollection('blog');
  const sorted = posts.sort((a, b) => b.data.pubDate - a.data.pubDate);
  return paginate(sorted, { pageSize: 10 });
}

const { page } = Astro.props;
// page.data: current page items
// page.currentPage: page number (1-indexed)
// page.url.next / page.url.prev: adjacent page URLs

6. Create

   src/pages/404.astro

   for a custom 404 page. In SSR mode this file is served for unmatched routes; in SSG it depends on the host.

7. Use

   Astro.redirect()

   for programmatic redirects in SSR mode. In SSG, configure redirects in

   astro.config.mjs

   :

// astro.config.mjs
export default defineConfig({
  redirects: {
    '/old-path': '/new-path',
    '/blog/[slug]': '/posts/[slug]', // dynamic redirect
  },
});

8. Understand route priority when multiple routes could match the same URL:
   • Static routes win over dynamic:

     /about

     beats

     [slug]

   • More specific dynamic routes win:

     /blog/[slug]

     beats

     /[...rest]

   • Named rest params lose to all other patterns

Details

Astro's file-based router has no runtime overhead in SSG mode — all route resolution happens at build time, producing a flat directory of

.html

getStaticPaths()

This function is called once per dynamic route file during the build. It must return a serializable array — the return value is cached and cannot be async per-entry (do all async work inside the function before mapping). Every params combination returned becomes a generated page. If a param is missing from the return value, that URL will 404.

Passing props through

getStaticPaths()

The

props

getStaticPaths()

Astro.props

params

Astro.params

• params

  in

  getStaticPaths()

  — the object you define that shapes the URL segments

• Astro.params

  — the resolved param values available in the frontmatter at render time. In SSG they match the params object you returned. In SSR they come from the live request URL.

Endpoint routes:

Files in

src/pages/

.ts

.js

.astro

Named groups and optional segments (Astro 4+):

• Optional params:

  [...slug]

  already acts as optional (can match zero segments)
• For a truly optional single segment, use

  [slug]

  with a rest route fallback or handle

  undefined

  in SSR

Hybrid SSR and routing:

In

output: 'hybrid'

export const prerender = false

getStaticPaths()

Astro.params

Source

https://docs.astro.build/en/guides/routing

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.