Day12 - Astro Series: Routes

@ Astro

A nice gradient background with a title: "Basic Routing"

Introduction

In the previous chapter we covered basic components, and as you probably guessed, any component placed inside src/pages/ will automatically become an Astro page. In this chapter we’ll take a closer look at Astro’s routing configuration.

Page routing

Astro uses a routing strategy called “File-based Routing”, so you can set up pages by arranging the folder structure inside pages. The following file types are supported:

  • .astro
  • .md
  • .mdx
  • .html
  • .js / .ts

Static routing

Every file inside pages becomes a corresponding page, for example:

Terminal window
src/pages/index.astro        -> mysite.com/
src/pages/about.astro        -> mysite.com/about
src/pages/about/index.astro  -> mysite.com/about
src/pages/about/me.astro     -> mysite.com/about/me
src/pages/posts/1.md         -> mysite.com/posts/1

Dynamic routing (SSG mode)

Simple static routes meet most needs, but sometimes you want pages created from data instead of manually making each one. That’s when “dynamic routing” comes in. Depending on the rendering mode, dynamic routes are written differently (SSG, SSR). This tutorial focuses on the static generation (SSG) approach.

For example, a blog may have hundreds of posts, and it’s impractical to create a page for each one manually. With dynamic routing you can auto-generate routes from data.

Because SSG requires determining all routes at build time, a dynamic route component must return a getStaticPaths function. This function returns an array of objects; each object must include a params property and may optionally include a props property.

---
export async function getStaticPaths() {
  return [
    { params: { /* Required */ }, props: { /* Optional */ } },
    { params: { ... } },
    { params: { ... } },
    // ...
  ];
}
---

The filename of the component acts as the parameter, and the returned params must include that parameter as a property. For example, a dynamic component at src/pages/authors/[author] can be written like this:

---
export async function getStaticPaths() {
  return [
    { params: { author: 'mike' } },
    { params: { author: 'joe' } },
    { params: { author: 'mary' } },
    // ...
  ];
}


const { author } = Astro.params;
---
<h1>The { author } Page</h1>

This generates three pages: /authors/mike, /authors/joe, and /authors/mary, each showing the corresponding author name — a basic dynamic route. Next, you can extract data and use map to build the required return array:

// Create pages/authors in [author].astro folder
---
export async function getStaticPaths() {
  // Define Page data
  const pages = [
    {
      slug: 'mike',
      author: "Mike",
      description: "Designer",
    },
    {
      slug: "joe",
      author: "Joe",
      description: "Backend",
    },
    {
      slug: "mary",
      author: "Mary",
      description: "Frontend",
    },
  ];


  // Build getStaticPaths
  return pages.map(({ slug, author, description}) => {
    return {
      params: { author: slug },
      props: { author, description },
    };
  });
}


// Destruct props
const { author, description } = Astro.props;
---


// Display props


作者:{author} - {description}

This creates three author pages in the pages/authors folder and displays the corresponding data. In this example the pages data is defined inside the component; in later chapters you’ll learn how to integrate a CMS or use Astro’s built-in Content Collections to import .md or .mdx files.

Catch-all / rest params

For more flexible page paths you can use a rest parameter [...path] in the .astro filename to match any depth. For example, the dynamic route pages/sequences/[...path].astro can produce three pages:

  1. /sequences/one/two/three
  2. /sequences/four
  3. /sequences

If you set the parameter to undefined it will match the top-level page; in this case /sequences.

---
export function getStaticPaths() {
  return [
    {params: {path: 'one/two/three'}},
    {params: {path: 'four'}},
    {params: {path: undefined }}
  ]
}
---

Other notes

404 page

To create a 404 error page simply add 404.astro or 404.md inside /src/pages.

Excluding pages

Terminal window
src/pages/
├── _hidden-directory/
│   ├── page1.md
│   └── page2.md
├── _hidden-page.astro
├── index.astro
└── posts/
    ├── _SomeComponent.astro
    ├── _utils.js
    └── post1.md

If you want to temporarily disable pages, prefix filenames or directories with an underscore _ to prevent them from being built. In the example above only post1.md and index.astro will be rendered.

Summary

This chapter covered creating Astro pages, focusing on static and dynamic routing in SSG mode, plus pagination and other small features.

Finally, recommended hands-on practice:

Further reading