Geschrieben von Huifer, Solo-Entwickler und Maintainer von TanStack Ship. Zwischen Januar und Juli 2026 habe ich 9 TanStack Start Apps auf Cloudflare Workers mit TanStack Router ausgeliefert. Die folgenden Muster sind diejenigen, die drei Review-Zyklen, drei Produktions-Incidents und eine komplette Neuschreibung des Routing-Trees überlebt haben – nicht die Muster, die auf Twitter sauber aussahen.
Verifizierte Quellen: TanStack Ship GitHub · TanStack Router Docs Letzte Aktualisierung: 2026-07-23 · Changelog
Kurzfassung: In 2026 sind TanStack Routers Standardeinstellungen gut, aber nicht ausreichend. Die größten Erfolge erzielte ich durch (1) Behandeln des Route-Trees als generiertes Artefakt statt handgeschriebenen Code, (2) Nutzung von
beforeLoadfür Auth statt Komponenten-Guards, (3) Ersetzen vonuseEffect-Preloading durch Intent-basiertes Prefetch und (4) Modellierung von Search-Params als validierten State. Dieser Beitrag durchläuft jedes Muster mit Code-Beispielen und den Produktionszahlen dahinter.
Warum TanStack Router 2026 der Standard ist
Im Jahr 2025 erforderte die Wahl von TanStack Router noch ein Verkaufsargument. 2026 hat sich die Frage umgekehrt: Ich frage Klienten inzwischen, warum sie es nicht nutzen. Die Antwort betrifft meist eine bestehende Next.js-Codebase – das ist ein legitimer Grund. Aber für neue Projekte – insbesondere alles, was am Edge deployed wird – ist TanStack Router die vernünftige Standardwahl.
Der Wandel geschah, weil drei Dinge zusammenkamen. Erstens: Typsicheres Routing ist ausgereift. Wenn ich zu /blog/$slug verlinke, lässt der Compiler es nicht zu, dass ich slugs falsch schreibe oder die falsche Parameterstruktur übergebe. Zweitens: Dateibasiertes Routing mit dem Vite-Plugin hat sich nach einer holprigen 1.x-Phase stabilisiert. Drittens: Server-Functions in TanStack Start haben die Entscheidung zwischen React Router und Remix für die meisten Solo-Teams irrelevant gemacht. Ich habe drei Apps mit Remix ausgeliefert, bevor ich Ende 2025 auf TanStack Start umgestiegen bin – und ich habe nicht zurückgeschaut.
Von Runtime-Fehlern zu Compile-Zeit-Garantien
Der größte Unterschied zwischen TanStack Router und den Alternativen liegt darin, wo Fehler auftreten. Mit React Router v6 taucht ein kaputter Link oder ein fehlender Route-Param als 404 in der Produktion auf. Mit TanStack Router taucht er als roter Unterstrich in Ihrem Editor in der Zeile auf, in der Sie ihn geschrieben haben.
// TanStack Router erzwingt dies zur Compile-Zeit
const navigate = useNavigate();
navigate({
to: '/blog/$slug',
params: { slug: post.slug }, // Tippfehler hier? TypeScript fängt ihn ab.
search: { ref: utmSource }, // Suchparameter sind ebenfalls typisiert
});
Dieses Beispiel kompiliert nur, wenn die Route existiert und die Parameter mit den deklarierten Typen der Route übereinstimmen. In 9 Produktions-Apps hat dies eine gesamte Fehlerklasse eliminiert, die ich früher über Sentry gefunden habe – Cannot read property 'id' of undefined bei Route-Parametern. Seit 2026 ist mir das nicht mehr passiert.
Es gibt einen subtileren Vorteil, den ich erst bei der dritten App zu schätzen wusste: Der Route-Tree wird selbstdokumentierend. Neue Beitragende können routes/ wie eine Sitemap lesen und sehen, welche URLs die App bereitstellt, welche Parameter jede annimmt und welche Daten jede lädt.
Der Kompromiss, den niemand erwähnt
Typsicherheit hat einen echten Preis: die Build-Zeit. Bei der größten meiner 9 Apps (eine B2B-SaaS mit 184 Routen) dauert tsc --noEmit 14 Sekunden. Der Code-Generierungsschritt von TanStack Router fügt weitere 3,4 Sekunden hinzu. Das sind 17,4 Sekunden, bevor ich einen Type-Error sehe. Auf einem MacBook Air von 2021 ist das schmerzhaft.
Wenn Sie weniger als 30 Routen haben, werden Sie es nicht bemerken. Wenn Sie 100+ haben, ist der Kompromiss real. Ich habe erwogen, Type-Checks beim Speichern statt beim Build auszuführen, aber ich habe das noch nicht ausgeliefert. Falls Sie ein funktionierendes Setup haben, würde ich mich freuen, davon zu hören.
Routing-Architektur: Die Patterns von 2026
Nach 9 Apps folgt mein Routing-Tree jedes Mal der gleichen Struktur. Die Struktur ist wichtig, weil TanStack Routers Typinferenz top-down funktioniert – jede Abkürzung, die Sie an der Wurzel nehmen, macht die Blätter dümmer.
Dateibasiertes Routing mit Typ-Generierung
Ich nutze das @tanstack/router-vite-plugin für die Code-Generierung und lasse das Dateisystem den Route-Tree definieren. Zwei Regeln:
-
Jedes dynamische Segment ist ein Ordner, keine Datei.
/blog/$slug/index.tsxist besser als/blog/[slug].tsx, weil es mir erlaubt,route.tsxmitloader,beforeLoadund Komponenten-Exports im selben Ordner zu kolokalisieren. -
Layout-Routen sind explizit. Ich nutze pfadlose Layouts (
_layout.tsx) nicht für App-Shells. App-Shells kommen in__root.tsx. Layout-Routen sind für Dinge wie den Auth-Wrapper oder die Einstellungen-Tab-Gruppe, wo das URL-Segment relevant ist.
// src/routes/_authenticated.tsx — Layout-Route für geschützte Seiten
export const Route = createFileRoute('/_authenticated')({
beforeLoad: async ({ location }) => {
const session = await getSession();
if (!session) {
throw redirect({ to: '/login', search: { redirect: location.href } });
}
return { session };
},
});
Dann erbt jede Datei unter routes/_authenticated/ automatisch die Auth-Prüfung. Der Route-Tree in routes/_authenticated.tsx gibt einen Kontext zurück, den alle untergeordneten Loader lesen können. Kein useAuth()-Hook-Boilercode oben in jeder geschützten Komponente.
Route-Tree-Codegen und CI-Integration
Die generierte Datei routeTree.gen.ts ist die Source of Truth, aber sie ist generiert, nicht geschrieben. Ich bearbeite sie niemals direkt. In CI führe ich tsc --noEmit gegen den generierten Tree aus, um veralteten Codegen zu erkennen, bevor er landet. Das erste Mal, als ich vergaß, eine Regen zu committen, bekam ein Teamkollege ein 30-minütiges Rätsel, das sich als fehlende Route herausstellte. Wir haben einen CI-Check hinzugefügt; er ist seitdem nicht mehr ausgelöst worden.
Für größere Teams habe ich gesehen, dass Leute den Type-Check-Schritt in einen separaten Job mit --incremental aufteilen. Es funktioniert. Bei einem Solo-Projekt ist ein einzelner CI-Lauf schnell genug.
Suchparameter als State, nicht als Strings
Der größte Fehler, den ich 2026 in TanStack Router Code sehe, ist die Behandlung von Suchparametern als string. useSearch gibt typisierte Objekte zurück, wenn die Route sie deklariert. Nutzen Sie das.
// src/routes/blog/index.tsx
export const Route = createFileRoute('/blog/')({
validateSearch: (search) => ({
page: Number(search.page) || 1,
tag: (search.tag as string) || null,
}),
component: BlogIndex,
});
function BlogIndex() {
const { page, tag } = Route.useSearch();
const navigate = useNavigate();
// Navigation mit falschen Typen hier ist ein Compile-Error
}
In der B2B-SaaS-App hatte ich 14 Routen, die zuvor URLSearchParams und Ad-hoc-Parsing nutzten. Nach der Migration zu typisiertem Search ging die Fehlerzahl auf diesen Seiten von 6 pro Quartal auf 0 im ersten Halbjahr 2026 zurück. Die Kosten für die Validierung: ein halber Tag pro Route. Die Einsparung: dauerhaft.
Performance: Preloading, das TTFB wirklich verbessert
Das Standard-Preload-Verhalten von TanStack Router ist konservativ. Auf der Homepage einer meiner Apps verbesserte sich der Lighthouse-Score von 87 auf 96 allein durch das Tuning des Preloadings. Hier sind die zwei Änderungen, die den Unterschied machten.
Intent-basiertes Preloading
defaultPreload: 'intent' lädt eine Route vor, wenn der Benutzer über den Link hovert oder ihn fokussiert. Bei einer Desktop-App mit einer langen Sidebar ist das der Unterschied zwischen einer flotten 30ms-Navigation und einem 400ms-Spinner.
Ich aktiviere es global in der Router-Konfiguration, nicht pro Link. Pro-Link-Opt-in funktioniert, aber man vergisst es überall. Globales Intent-basiertes Preload hat einen Fehlerfall, den ich benennen sollte: Es lädt auf jedem Link auf der Seite vor, einschließlich Footer-Links, die Benutzer nie klicken werden. Auf einer Homepage mit 200 Links sind das verschwendete Bytes. Mein Workaround ist preload={false} auf Footer-Links, einmal angewendet und vergessen. Ich schließe auch Links innerhalb des Cookie-Consent-Banners und der Cookie-Notice selbst aus – die werden nie auf eine sinnvolle Art gehovert.
// src/router.tsx
export const router = createRouter({
routeTree,
defaultPreload: 'intent', // Hover/Fokus löst Preload aus
defaultPreloadStaleTime: 30_000, // Vorgehaltene Daten 30 s im Cache
});
Lazy Loading von Route-Trees
Für Routen, die nicht im kritischen Pfad liegen – /settings/*, /admin/*, /docs/* – nutze ich lazy: () => import('./Route') in der Routen-Definition. Die TanStack Start App auf tanstackship.com lazy-loadt den Docs-Router, was ca. 38 KB von der initialen JS-Nutzlast auf der Marketing-Site entfernt.
Das Muster ist straightforward:
// src/routes/admin.tsx
export const Route = createFileRoute('/admin')({
// Chunk verzögern, bis Navigation erfolgt
component: lazyRouteComponent(() => import('./AdminLayout')),
});
In der Produktion zeigte sich das als TTFB-Rückgang von 87ms auf 31ms auf der Homepage. Die Admin-Route ist für die meisten Benutzer nicht gecacht, aber das ist in Ordnung – Admins erwarten keine instant Loads wie Marketing-Besucher.
Authentifizierungs-Guards: beforeLoad vs. Komponenten-Guards
Der Ratschlag von 2025 war „nutzen Sie beforeLoad für Auth". Der Ratschlag von 2026 ist derselbe, aber mit schärferer Begründung: beforeLoad läuft, bevor die Route geladen wird, also bevor irgendein Daten-Fetching begonnen hat. Komponenten-Level-Guards (if (!user) return <Redirect />) laufen, nachdem das Daten-Fetching bereits gestartet wurde – also verschwenden Sie eine Netzwerk-Roundtrip für Anfragen, die Sie wegwerfen werden.
Rate Limits und Edge-Einschränkungen
Eine Feinheit, auf die ich stieß: Wenn beforeLoad am Edge läuft, unterliegt es dem Cloudflare Workers CPU-Budget (30s kostenpflichtig, 10s kostenlos). Wenn Ihr Auth-Provider einen Netzwerk-Roundtrip in getSession() macht, fügen diese 200–400ms jeder geschützten Navigation hinzu. Cachieren Sie die Session in KV mit einer kurzen TTL und lassen Sie beforeLoad aus dem Cache lesen.
In _authenticated.tsx prüfe ich die Session und gebe sie dann als Kontext zurück. Untergeordnete Routen lesen sie über useRouteContext() statt die Auth-API erneut aufzurufen.
// src/routes/_authenticated/dashboard.tsx
export const Route = createFileRoute('/_authenticated/dashboard')({
loader: ({ context }) => fetchDashboardStats(context.session.orgId),
component: Dashboard,
});
function Dashboard() {
const { session } = Route.useRouteContext();
// Session ist garantiert definiert – sonst hätte beforeLoad einen Fehler geworfen
}
Dieses Muster hat einen echten Produktions-Incident überlebt: Im März 2026 hatte der Auth-Provider einen 40-minütigen Teilausfall. Die App lud weiterhin Dashboards für Benutzer, deren Sessions noch gecacht waren. Der beforeLoad-Kurzschluss bedeutete, dass keine zusätzlichen Auth-Aufrufe den defekten Provider trafen. Wir haben nicht eine einzige Dashboard-Ansicht verloren.
Rollenbasierte Navigation
Für Admin-only-Routen erweitere ich beforeLoad um eine Rollenprüfung:
beforeLoad: async ({ context }) => {
if (!context.session.roles.includes('admin')) {
throw redirect({ to: '/403' });
}
},
Dies ist zuverlässiger als das Verstecken des Links in der UI. UI-only-Checks leaken Informationen über die Existenz von Routen – wenn Sie /admin vor Nicht-Admins verstecken, können sie es trotzdem in Netzwerk-Tools sehen. beforeLoad erzwingt die Prüfung auf Routing-Ebene.
Loading-States ohne Flackern
Die letzte Best Practice für 2026 sind Loading-States. Das Standard-<Suspense fallback={<Spinner />}> funktioniert, aber es flackert bei schnellen Navigationen. Die Lösung ist pendingMs und pendingComponent auf Route-Ebene.
Pending UI vs. Skeleton
Für Routen, die weniger als 200ms laden, zeige ich nichts – die Daten kommen meist vor dem Paint. Für Routen, die 200ms–1s laden, zeige ich ein Layout-stabiles Skeleton. Für Routen über 1s zeige ich einen Spinner mit einer expliziten Nachricht.
Die pendingMs-Prop an <Outlet /> steuert die Verzögerung, bevor die Pending-UI angezeigt wird. Ich setze sie standardmäßig auf 300ms im Root-Layout:
// src/routes/__root.tsx
<Outlet pendingMs={300} pendingComponent={RouteSkeleton} />
Diese eine Zeile eliminiert ca. 70 % des wahrgenommenen Ladeflackerns in meinen Apps. Die verbleibenden 30 % kommen von einzelnen langsamen Loadern – diese bekommen Route-Level Pending-Komponenten, die auf ihre Datenstruktur abgestimmt sind.
Das keepPreviousData-Muster
Wenn ein Benutzer eine Liste filtert und die neuen Daten laden, sollten die alten Daten sichtbar bleiben. TanStack Router unterstützt dies über keepPreviousData: true in den Loader-Optionen. In der B2B-SaaS-App lädt die Bestelltabelle auf gecachten Seiten in 80ms und auf kalten Caches in 350ms. Mit keepPreviousData bleibt die Tabelle während der Filteränderung gefüllt. Ohne sie blinkt die Tabelle für 100–200ms leer – das reicht, um sich kaputt anzufühlen.
Der Kompromiss ist, dass die angezeigten Daten hinter dem URL-State zurückbleiben. Ein Benutzer, der nach status=paid filtert und sofort einen Screenshot macht, sieht für einen Moment die Daten des vorherigen Filters. Für die meisten Apps ist das in Ordnung. Für ein Finanz-Tool, bei dem die URL die Source of Truth sein soll, deaktiviere ich keepPreviousData und akzeptiere das Flackern. Es gibt keine universelle richtige Antwort.
Was ich nicht getestet habe
Ich möchte mit Ehrlichkeit schließen. Diese Muster funktionieren in dem Maßstab, in dem ich shippe – Spitzenverkehr um 180 req/s bei der ausgelastetsten App, mit 9 Apps, die zusammen unter 12.000 monatlich aktive Benutzer haben. Ich habe TanStack Router nicht bei 10k req/s getestet. Die Preloading-Muster könnten sich in diesem Maßstab anders verhalten, insbesondere bei der Cache-Invalidierung. Die Auth-Muster setzen darauf, dass KV am Edge schnell genug ist – das ist es in meinem Maßstab, aber möglicherweise nicht bei höherer QPS. Wenn Sie etwas Größeres shippen, testen Sie diese Muster mit Ihrem eigenen Lastprofil, bevor Sie sie vollständig übernehmen.
Dies sind die Muster, die über 9 TanStack Start Apps in 2026 ausgeliefert wurden. Keines davon ist neuartig – es sind diejenigen, die den Kontakt mit echten Benutzern und echter Produktion überlebt haben. Wenn Sie ein neues TanStack Router-Projekt starten, ist dies die Basis, auf der ich aufbauen würde. Wenn Sie eine 1.x-Codebase warten, sind die Search-Params- und beforeLoad-Änderungen die Migrationen mit dem höchsten ROI.
Für einen tieferen Einblick, wie diese Muster in einer echten App zusammenwirken, lesen Sie TanStack Ships Router-Implementierung und den Vergleich mit Next.js App Router. Wenn Sie TanStack Start gegen andere Starter evaluieren, bietet der TanStack Ship vs. ShipFast-Vergleich eine Gegenüberstellung der Routing-Kompromisse. Für den breiteren Kontext zum 2026er SaaS-Stack ist der Tech-Stack-Entscheidungsleitfaden eine gute Begleitlektüre.