Astro JS Routing 2026 – Dateibasiertes Routing für statische und dynamische Websites
Astro JS Routing ist ein dateibasiertes Routing-System, das URL-Strukturen direkt aus der Verzeichnisstruktur im src/pages/-Ordner ableitet. Jede .astro-, .md- oder .mdx-Datei wird automatisch zu einer Route – ohne manuelle Konfiguration, ohne Router-Bibliothek.
Das Routing-System unterstützt statische Routen, dynamische Parameter mit eckigen Klammern, Rest-Parameter für Catch-All-Routen, API-Endpunkte und seit Astro 5 integriertes i18n-Routing. Seit der Cloudflare-Übernahme im Januar 2026 und dem Astro 6 Release wird das Routing-System mit der workerd-Runtime und Content Layer API weiterentwickelt. Bei Never Code Alone setzen wir Astro-Routing neben Sulu CMS für performante Frontend-Projekte ein.
Statische, dynamische und API-Routen in Astro
Astros Routing-System leitet alle URL-Pfade aus der Verzeichnisstruktur unter src/pages/ ab. Jede Datei wird zu einer Route: src/pages/about.astro ergibt /about, ein Ordner src/pages/blog/ mit index.astro ergibt /blog. Verschachtelte Ordner erzeugen verschachtelte Pfade – ohne Konfigurationsdatei, ohne Router-Setup.
Für dynamische Routen werden eckige Klammern verwendet: [slug].astro matcht einen einzelnen URL-Parameter, [...slug].astro als Rest-Parameter matcht beliebig viele Segmente (Catch-All-Routen). Im Static-Modus muss getStaticPaths() alle möglichen Parameter zur Build-Zeit zurückgeben. Im Server-Modus mit Adapter werden Parameter zur Laufzeit aus der URL gelesen – ideal für dynamische Inhalte.
src/pages/
├── index.astro # → /
├── about.astro # → /about
├── blog/
│ ├── index.astro # → /blog
│ ├── [slug].astro # → /blog/mein-artikel
│ └── [...path].astro # → /blog/2026/01/titel
└── api/
└── search.ts # → /api/search (API-Endpunkt)
API-Endpunkte werden durch .ts- oder .js-Dateien im pages-Verzeichnis definiert, die HTTP-Methoden wie GET, POST, PUT oder DELETE als benannte Exports bereitstellen. Im Static-Modus generieren API-Routen statische JSON-Dateien, im Server-Modus verarbeiten sie Requests dynamisch. Die Routing-Priorität folgt einer klaren Rangfolge: statische Routen haben Vorrang vor dynamischen, und spezifische Parameter vor Rest-Parametern.
i18n-Routing und Konfiguration in Astro 2026
Seit Astro 5 ist internationalisiertes Routing direkt im Framework integriert. Über die i18n-Konfiguration in der astro.config.mjs werden Sprachen, Standard-Locale und Routing-Strategien definiert. Astro generiert automatisch sprachspezifische URL-Pfade und stellt Hilfsfunktionen für Spracherkennung und Redirects bereit.
// astro.config.mjs – i18n-Routing
import { defineConfig } from 'astro/config';
export default defineConfig({
i18n: {
defaultLocale: 'de',
locales: ['de', 'en', 'fr'],
routing: {
prefixDefaultLocale: false
}
}
});
Mit prefixDefaultLocale: false erscheint die Standardsprache ohne Prefix in der URL: /about statt /de/about. Andere Sprachen erhalten ihr Kürzel als Prefix: /en/about, /fr/about. Die Astro-Middleware stellt Astro.currentLocale bereit, um die aktive Sprache in Komponenten zu nutzen. Für Content-Routing mit Markdown oder MDX nutzt Astro die Content Layer API, die in Astro 6 mit Live Content Collections erweitert wurde – Inhalte können zur Laufzeit ohne Rebuild abgerufen werden.
Zusätzlich lässt sich das Trailing-Slash-Verhalten über trailingSlash in der Config steuern ('always', 'never' oder 'ignore'). Die base-Option ermöglicht das Deployment in Unterverzeichnissen wie /docs/. Für Redirects bietet Astro sowohl statische Redirects in der Config als auch dynamische Redirects über Astro.redirect() im Server-Modus.
Häufig gestellte Fragen (FAQ)
Die wichtigsten Fragen zum Astro JS Routing – von dateibasierten Routen über dynamische Parameter bis zu i18n und API-Endpunkten.
Was ist Astro JS Routing und wie funktioniert es 2026?
Astro JS Routing ist ein dateibasiertes System, das URL-Strukturen direkt aus der Verzeichnisstruktur im src/pages/-Ordner ableitet. Jede .astro-, .md- oder .mdx-Datei wird automatisch zu einer Route ohne manuelle Konfiguration. Im Jahr 2026 unterstützt Astro statische Routen, dynamische Parameter, Rest-Parameter, API-Endpunkte und integriertes i18n-Routing.
Welche Routing-Typen unterstützt Astro 2026?
Astro unterstützt vier Routing-Typen: Statische Routen durch reguläre Dateien, dynamische Routen mit eckigen Klammern wie [slug].astro, Catch-All-Routen mit Rest-Parametern wie [...path].astro und API-Endpunkte durch .ts/.js-Dateien die HTTP-Methoden exportieren. Im Server-Modus kommen dynamische SSR-Routen hinzu.
Wie erstelle ich dynamische Routen mit Astro 2026?
Dynamische Routen werden durch eckige Klammern im Dateinamen definiert: [id].astro matcht einen einzelnen Parameter, [...slug].astro matcht beliebig viele Segmente. Im Static-Modus muss getStaticPaths() alle möglichen Werte zur Build-Zeit zurückgeben. Im Server-Modus mit Adapter werden Parameter dynamisch zur Laufzeit aus der URL gelesen.
Wie konfiguriere ich i18n-Routing in Astro 2026?
Astro bietet seit Version 5 integriertes i18n-Routing über die astro.config.mjs. Du definierst defaultLocale, locales und die Routing-Strategie. Mit prefixDefaultLocale: false erscheint die Hauptsprache ohne URL-Prefix. Astro stellt Astro.currentLocale in Komponenten bereit und generiert automatisch sprachspezifische URL-Pfade für alle konfigurierten Sprachen.
Was ändert sich am Astro Routing mit Astro 6 und Cloudflare 2026?
Seit der Cloudflare-Übernahme im Januar 2026 nutzt der Astro 6 Dev-Server die workerd-Runtime für Development-Production-Parity. Das Routing profitiert von Live Content Collections für Runtime-Datenfetching ohne Rebuild und besserer Integration mit Cloudflare Workers. Server-seitige Routen laufen am Edge mit Zugriff auf KV, R2 und Durable Objects.
Wie funktionieren API-Routen in Astro?
API-Endpunkte werden als .ts- oder .js-Dateien im pages-Verzeichnis angelegt. Sie exportieren benannte Funktionen für HTTP-Methoden wie GET, POST, PUT oder DELETE. Im Static-Modus generieren sie statische JSON-Dateien beim Build. Im Server-Modus verarbeiten sie Requests dynamisch und haben Zugriff auf Cookies, Headers und Request-Body.
Wie funktioniert die Routing-Priorität in Astro?
Astro folgt einer klaren Prioritätsreihenfolge: Statische Routen haben Vorrang vor dynamischen Routen, spezifische dynamische Parameter vor Rest-Parametern. Bei Konflikten zwischen gleichrangigen Routen wird alphabetisch aufgelöst. Diese Reihenfolge gilt für Dateien im selben Verzeichnis und ist unabhängig davon, ob die Seite prerendered oder server-rendered wird.
Kann ich in Astro Redirects konfigurieren?
Ja, Astro bietet zwei Arten von Redirects. Statische Redirects werden in der astro.config.mjs unter redirects definiert und beim Build in HTML-Meta-Redirects oder Server-Regeln umgewandelt. Dynamische Redirects nutzen Astro.redirect() im Server-Modus für bedingte Weiterleitungen basierend auf Cookies, Authentifizierung oder anderen Laufzeitbedingungen.
Wie unterscheidet sich Astro Routing von Next.js Routing?
Beide nutzen dateibasiertes Routing, aber Astro generiert standardmäßig statisches HTML ohne JavaScript-Runtime. Next.js lädt immer eine React-Runtime für Client-Side-Navigation. Astro unterstützt Multi-Framework-Routing auf einer Seite, Next.js ist React-exklusiv. Astros Routing ist leichter und schneller für content-getriebene Websites, Next.js bietet mehr Features für komplexe Applikationen.
Was sind Rest-Parameter und Catch-All-Routen in Astro?
Rest-Parameter werden mit drei Punkten definiert: [...slug].astro. Sie matchen beliebig viele URL-Segmente, zum Beispiel /blog/2026/01/mein-titel. Der Parameter enthält den gesamten Pfad als String. Das eignet sich für verschachtelte Kategorien, Datums-URLs oder flexible Content-Strukturen ohne feste Tiefe. Im Static-Modus muss getStaticPaths() alle Kombinationen liefern.
Wie erstelle ich eine 404-Seite in Astro?
Eine benutzerdefinierte 404-Seite wird als src/pages/404.astro angelegt. Astro erkennt diesen Dateinamen automatisch und nutzt die Seite für alle nicht gefundenen Routen. Im Static-Modus wird eine statische 404.html erzeugt, die der Webserver ausliefert. Im Server-Modus kann die 404-Seite dynamisch gerendert werden und auf Request-Daten zugreifen.
Wie funktioniert Content-Routing mit Markdown in Astro?
Markdown-Dateien im pages-Verzeichnis werden automatisch zu Routen. Für strukturierte Blog-Posts nutzt Astro Content Collections mit der Content Layer API. In Astro 6 ermöglichen Live Content Collections das Laden von Inhalten zur Laufzeit ohne Rebuild. Die Frontmatter-Daten stehen für dynamische Routing-Parameter, Filterung und Sortierung zur Verfügung.
Wie konfiguriere ich Trailing Slashes im Astro Routing?
Über die trailingSlash-Option in der astro.config.mjs wird gesteuert, ob URLs mit Slash enden oder nicht. Die Einstellung 'always' erzwingt Trailing Slashes, 'never' entfernt sie, 'ignore' akzeptiert beides. Für SEO ist eine konsistente Wahl wichtig, um Duplicate-Content-Probleme zu vermeiden. Die Einstellung beeinflusst auch die Dateistruktur im Build-Output.
Kann ich Astro Routing mit einem Headless CMS verbinden?
Ja, Astro eignet sich hervorragend für Headless-CMS-Setups. Dynamische Routen laden Inhalte aus CMS-APIs wie Sulu, Strapi, Contentful oder Sanity. Im Static-Modus werden alle CMS-Einträge über getStaticPaths() zur Build-Zeit abgerufen. Im Server-Modus können Inhalte zur Laufzeit per API-Call geladen werden – ideal für häufig aktualisierte Inhalte.
Wie teste und debugge ich Astro Routing lokal?
Der Astro Dev-Server startet mit npm run dev und zeigt alle verfügbaren Routen in der Konsole an. In Astro 6 nutzt der Dev-Server die gleiche Runtime wie die Produktion für konsistentes Verhalten. Routing-Fehler wie fehlende getStaticPaths-Einträge oder doppelte Routen werden als Build-Warnungen angezeigt. Die Astro CLI bietet zudem einen Preview-Modus für den fertigen Build.
Fazit: Astro JS Routing – einfach, performant und flexibel
Das dateibasierte Routing in Astro gehört zu den größten Stärken des Frameworks: kein Router-Setup, keine Konfigurationsdateien, eine klare 1:1-Beziehung zwischen Verzeichnisstruktur und URL-Pfaden. Dynamische Parameter, Rest-Routen, API-Endpunkte und integriertes i18n-Routing decken alle gängigen Anwendungsfälle ab – vom statischen Blog bis zur mehrsprachigen E-Commerce-Seite.
Mit Astro 6 und der Cloudflare-Integration wird das Routing-System 2026 noch leistungsfähiger: Live Content Collections für Runtime-Content, workerd-Runtime für konsistentes Dev/Prod-Verhalten und native Edge-Deployment-Unterstützung. Für content-getriebene Websites, die Performance, SEO und Barrierefreiheit vereinen müssen, ist Astro-Routing die technisch fundierte Wahl.
Du planst ein Frontend-Projekt mit Astro oder brauchst Unterstützung bei der Integration von i18n-Routing, Headless CMS oder CI/CD-Pipelines? Bei Never Code Alone verbinden wir Astro-Frontend-Expertise mit Backend-Know-how aus Sulu CMS und Symfony. Vereinbare eine kostenlose Erstberatung unter roland@nevercodealone.de oder ruf direkt an: +49 176 24747727.