Complete Guide to Astro Routing System

Routing Fundamentals

1. File System Routing

Astro uses convention-based routing based on directory structure:

src/pages/
├─ index.astro         => /
├─ about.astro         => /about
├─ blog/
│  ├─ index.astro      => /blog
│  └─ [slug].astro     => /blog/:slug
└─ [[...path]].astro   => 404 page

2. Routing Features Comparison

Feature	Astro	Next.js	Nuxt
Routing Mode	File System	File System + Config	File System
Dynamic Parameters	`[param]` syntax	`[param]` syntax	`:param` syntax
Route Priority	Alphabetical	Path Depth First	Path Depth First
Wildcard Routes	Supports `[...path]`	Supports `[[...path]]`	Supports `_:path`

Route Types in Detail

1. Static Routes

Basic page routing:

<!-- src/pages/contact.astro -->
---
// Page logic
---
<html>
  <body>
    <h1>Contact Us</h1>
  </body>
</html>

2. Dynamic Routes

Basic Dynamic Parameters:

<!-- src/pages/users/[id].astro -->
---
const { id } = Astro.params;
---
<p>User ID: {id}</p>

Multi-Segment Parameters:

<!-- src/pages/docs/[lang]/[version]/[...slug].astro -->
---
const { lang, version, slug } = Astro.params;
// When accessing /docs/en/1.0/getting-started:
// lang => 'en', version => '1.0', slug => 'getting-started'

3. RESTful Routes

File Path	Matching Path	Parameter Access
pages/products/[id].astro	/products/123	`{ id: '123' }`
pages/[…all].astro	/any/path/here	`{ all: 'any/path/here' }`

Advanced Routing Features

1. Route Redirects

redirects.config.mjs configuration:

// Static redirects
export const get = () => [
    {
        source: '/old-about',
        destination: '/about',
        status: 301,
    },
    // Dynamic redirects
    {
        source: '/user/:id',
        destination: '/users/:id',
        status: 302,
    },
];

2. Route Middleware

Creating middleware file:

// src/middleware/auth.js
export const onRequest = async (context, next) => {
    if (!context.locals.user) {
        return new Response('Unauthorized', { status: 401 });
    }
    return next();
};

Applying middleware:

<!-- src/pages/dashboard.astro -->
---
import middleware from '../middleware/auth';
export const onRequest = middleware;
// Page logic...
---

Routing Optimization Techniques

1. Route Prefetching

<a href="/about" data-astro-prefetch>About Us</a>

Global prefetch configuration:

// astro.config.mjs
export default defineConfig({
    prefetch: {
        prefetchAll: true,
        defaultStrategy: 'viewport',
    },
});

2. Route Splitting

Loading components on demand:

---
const HeavyComponent = await import('../components/Heavy.astro');
---
<HeavyComponent />

Internationalization Routes

Multilingual Route Configuration

// astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
    integrations: [
        starlight({
            locales: {
                root: { label: 'English', lang: 'en' },
                zh: { label: '中文', lang: 'zh' },
            },
        }),
    ],
});

Directory structure:

src/content/docs/
├─ en/
│  └─ getting-started.md
└─ zh/
   └─ getting-started.md

Common Issues

Q1: How to Handle Route Conflicts?

Priority rules:

Static routes take precedence over dynamic routes
Routes with more parameters take precedence
Alphabetical sorting

Q2: How to Implement Custom 404 Pages?

Create src/pages/[[...path]].astro:

---
import NotFound from '../layouts/NotFound.astro';
---
<NotFound />

Performance Optimization

1. Hybrid Rendering Modes

// Page-level configuration
export const getStaticPaths = () => [
    { params: { id: '1' } }, // Static generation
    { params: { id: '2' }, props: { ssr: true } }, // Server-side rendering
];

2. Incremental Static Generation

// src/pages/products/[id].astro
export const getStaticPaths = async () => {
    const products = await fetch('https://api.example.com/products');
    return products.map(product => ({
        params: { id: product.id },
        props: { product },
        // Revalidate every 24 hours
        revalidate: 60 * 60 * 24,
    }));
};

Best Practices

Naming Conventions: Use lowercase letters and hyphens (kebab-case)
Dynamic Parameters: Prefer explicit parameter names (e.g., [userId] over [id])
Performance Optimization: Enable prefetching and preloading for high-frequency pages
Security Protection: Strictly validate dynamic route parameters

Conclusion

Astro’s routing system provides a powerful and flexible foundation for building modern web applications. By understanding and properly implementing these routing features, you can create efficient, maintainable, and user-friendly applications.