Kurs Next.js · Moduł 9: Integracje i zaawansowane funkcje
Typed Routes - Bezpieczne linki z TypeScript
W tej lekcji12
W systemach nawigacyjnych Metropolii Quantum 2150 jeden zły adres wysyła transport do nieistniejącego doku. W aplikacji wygląda to niewinnie: literówka w href, TypeScript milczy, a użytkownik po kliknięciu trafia na stronę 404. Matrix, strażnik tras Metropolii, każe więc sprawdzać każdą ścieżkę jeszcze przed startem. Umożliwia to Typed Routes - funkcja Next.js, która zapewnia type-safety dla ścieżek w aplikacji.
Problem: Błędy w ścieżkach
Bez Typed Routes ścieżki są zwykłymi stringami, więc kompilator przyjmie każdy tekst:
// Łatwo o literówkę - brak walidacji w TypeScript
<Link href="/prodcuts">Produkty</Link> // Literówka!
<Link href="/users/123/setings">Ustawienia</Link> // Znowu literówka!
// Brak sprawdzania parametrów
redirect('/products/' + productId); // Co jeśli productId jest undefined?Wszystkie trzy linie się skompilują, a błędy wyjdą dopiero u użytkownika.
Rozwiązanie: Typed Routes
Typed Routes automatycznie generuje typy dla wszystkich ścieżek w aplikacji na podstawie struktury katalogu app.
Włączenie Typed Routes
Od Next.js 15.5 opcja typedRoutes jest stabilna i ustawiasz ją na najwyższym poziomie konfiguracji. Wcześniej była ukryta w obiekcie experimental:
// next.config.js
module.exports = {
typedRoutes: true,
};Po włączeniu i uruchomieniu next dev, next build lub next typegen Next.js wygeneruje w katalogu .next/types plik z definicjami wszystkich tras. Projekt musi używać TypeScriptu, a tsconfig.json musi obejmować .next/types/**/*.ts.
Podstawowe użycie
Link z walidacją
Komponent Link z next/link przyjmuje teraz w href tylko istniejące ścieżki:
import Link from 'next/link';
function Navigation() {
return (
<nav>
{/* Poprawne ścieżki - TypeScript OK */}
<Link href="/">Home</Link>
<Link href="/products">Produkty</Link>
<Link href="/about">O nas</Link>
{/* Błędna ścieżka - TypeScript Error! */}
<Link href="/prodcuts">Produkty</Link>
{/* Type '"prodcuts"' is not assignable to type 'Route' */}
</nav>
);
}Literówka /prodcuts staje się błędem kompilacji z komunikatem, że tekst nie pasuje do typu Route. Poprawne linki działają dokładnie tak jak wcześniej.
Dynamiczne segmenty
Segmenty dynamiczne, jak [id], przyjmują dowolną wartość w swoim miejscu, ale reszta ścieżki musi się zgadzać:
// Dla struktury: app/products/[id]/page.tsx
<Link href="/products/123">Produkt 123</Link> // OK
// Dla struktury: app/users/[userId]/posts/[postId]/page.tsx
<Link href="/users/456/posts/789">Post</Link> // OKTypeScript sprawdza kształt adresu, a nie to, czy produkt 123 istnieje w bazie.
useRouter z typami
W App Routerze typowane są też metody routera z next/navigation: push, replace i prefetch:
'use client';
import { useRouter } from 'next/navigation';
function ProductActions({ productId }: { productId: string }) {
const router = useRouter();
const handleEdit = () => {
// TypeScript sprawdza poprawność ścieżki
router.push(`/products/${productId}/edit`);
};
const handleDelete = () => {
// Poprawne
router.push('/products');
};
const handleBroken = () => {
// TypeScript Error jeśli /prodcts nie istnieje
router.push('/prodcts');
};
return (
<div>
<button onClick={handleEdit}>Edytuj</button>
<button onClick={handleDelete}>Usuń</button>
</div>
);
}Szablon /products/${productId}/edit jest akceptowany, bo pasuje do wzorca trasy, a /prodcts zostanie odrzucone.
redirect() z typami
Ścieżki przekazywane do redirect() warto trzymać w tej samej dyscyplinie:
import { redirect } from 'next/navigation';
async function ProtectedPage() {
const session = await getSession();
if (!session) {
// TypeScript sprawdza ścieżkę
redirect('/login');
}
if (!session.isVerified) {
// Poprawne
redirect('/verify-email');
}
return <Dashboard />;
}Dokumentacja Next.js wymienia wprost typowanie Link i metod routera, dlatego przy redirect() najbezpieczniej korzystać ze stałych typu Route, które poznasz za chwilę.
Pomocnik Route
Next.js generuje typ Route importowany z pakietu next, którego możesz używać we własnych funkcjach:
import type { Route } from 'next';
// Funkcja akceptująca tylko poprawne ścieżki
function navigateTo(path: Route) {
window.location.href = path;
}
navigateTo('/products'); // OK
navigateTo('/prodcuts'); // ErrorFunkcja przyjmie tylko adres istniejącej strony, więc błąd pojawi się już przy wywołaniu.
Typ dla dynamicznych ścieżek
Gdy adres składasz z nieliteralnego stringa, TypeScript nie zna jego wartości, więc potrzebujesz asercji as Route:
import type { Route } from 'next';
// Funkcja generująca link do produktu
function getProductUrl(id: string): Route {
return `/products/${id}` as Route;
}
// Użycie
<Link href={getProductUrl('123')}>Produkt</Link>Asercja to obietnica złożona kompilatorowi, dlatego zamknij ją w jednej funkcji pomocniczej, zamiast rozsiewać po całej aplikacji.
Praca z parametrami wyszukiwania
Parametry zapytania nie są częścią definicji trasy, więc możesz je dodać obiektem albo w stringu:
import Link from 'next/link';
function ProductFilters() {
return (
<div>
{/* Ścieżka z query params */}
<Link
href={{
pathname: '/products',
query: { category: 'electronics', sort: 'price' },
}}
>
Elektronika (sortuj po cenie)
</Link>
{/* Lub jako string */}
<Link href="/products?category=electronics&sort=price">
Elektronika
</Link>
</div>
);
}W obu przypadkach sprawdzana jest ścieżka /products, a parametry category i sort pozostają dowolne.
Praktyczny przykład - Nawigacja E-commerce
W prawdziwej aplikacji linki trzymasz w jednym miejscu. Interfejs NavigationItem wymaga, żeby pole href było typu Route:
// types/navigation.ts
import type { Route } from 'next';
export interface NavigationItem {
label: string;
href: Route;
icon?: React.ReactNode;
}
export const mainNavigation: NavigationItem[] = [
{ label: 'Home', href: '/' },
{ label: 'Produkty', href: '/products' },
{ label: 'Kategorie', href: '/categories' },
{ label: 'O nas', href: '/about' },
{ label: 'Kontakt', href: '/contact' },
];
export const userNavigation: NavigationItem[] = [
{ label: 'Profil', href: '/account/profile' },
{ label: 'Zamówienia', href: '/account/orders' },
{ label: 'Ustawienia', href: '/account/settings' },
];Usunięcie strony /contact z katalogu app od razu podkreśli błąd w tej tablicy.
Komponent nawigacji tylko renderuje tę tablicę:
// components/MainNav.tsx
import Link from 'next/link';
import { mainNavigation } from '@/types/navigation';
export function MainNav() {
return (
<nav className="flex gap-6">
{mainNavigation.map((item) => (
<Link
key={item.href}
href={item.href} // TypeScript wie, że to poprawna ścieżka
className="hover:text-blue-500"
>
{item.label}
</Link>
))}
</nav>
);
}Komponent nie zawiera żadnego adresu wpisanego ręcznie, więc nie ma w nim miejsca na literówkę.
Breadcrumbs z Typed Routes
Okruszki chleba mają opcjonalne href, bo ostatni element to bieżąca strona, która nie jest linkiem:
// components/Breadcrumbs.tsx
import Link from 'next/link';
import type { Route } from 'next';
interface BreadcrumbItem {
label: string;
href?: Route;
}
interface BreadcrumbsProps {
items: BreadcrumbItem[];
}
export function Breadcrumbs({ items }: BreadcrumbsProps) {
return (
<nav aria-label="Breadcrumb" className="flex items-center gap-2 text-sm">
{items.map((item, index) => (
<span key={index} className="flex items-center gap-2">
{index > 0 && <span className="text-gray-400">/</span>}
{item.href ? (
<Link href={item.href} className="text-blue-600 hover:underline">
{item.label}
</Link>
) : (
<span className="text-gray-600">{item.label}</span>
)}
</span>
))}
</nav>
);
}
// Użycie
<Breadcrumbs
items={[
{ label: 'Home', href: '/' },
{ label: 'Produkty', href: '/products' },
{ label: 'Elektronika', href: '/products?category=electronics' },
{ label: 'Smartphone X' }, // Ostatni element bez linku
]}
/>Typ href?: Route pozwala pominąć link, ale jeśli już go podasz, musi być poprawny.
Ograniczenia Typed Routes
1. Dynamiczne segmenty
TypeScript sprawdza wzorzec trasy, ale nie wartość wstawianą w miejsce segmentu:
// TypeScript nie może sprawdzić wartości dynamicznego segmentu
const id = getUserInput();
<Link href={`/products/${id}`}>Produkt</Link> // Przyjmie każdy string
// Możesz użyć asercji typu jeśli jesteś pewien
<Link href={`/products/${id}` as Route}>Produkt</Link>Dane od użytkownika waliduj osobno, bo typ nie powie ci, czy taki produkt istnieje.
2. Zewnętrzne linki
Adresy spoza aplikacji nie są typu Route:
// Zewnętrzne URL nie są Route
<Link href="https://google.com">Google</Link> // Error
// Użyj zwykłego <a> dla zewnętrznych linków
<a href="https://google.com">Google</a>Dla linków zewnętrznych używaj zwykłego znacznika a, najlepiej z rel="noopener noreferrer" przy otwieraniu w nowej karcie.
3. Catch-all routes
Segment catch-all [...slug] przyjmuje dowolną liczbę członów po prefiksie:
// Dla app/docs/[...slug]/page.tsx
// TypeScript sprawdzi prefix, ale nie całą ścieżkę
<Link href="/docs/getting-started/installation">Docs</Link> // OKSprawdzany jest tylko prefiks /docs/, a to, czy dana podstrona dokumentacji istnieje, wychodzi dopiero w trakcie działania.
Konfiguracja segmentów też jest sprawdzana
Wbudowany plugin TypeScript Next.js pilnuje także eksportów konfiguracji segmentu. Taki eksport składa się ze słów export const, nazwy opcji, znaku = i wartości:
// app/products/page.tsx
export const fetchCache = 'force-cache';Plugin ostrzeże, jeśli wpiszesz nieistniejącą wartość, np. 'force-cash'. Pamiętaj, że w Next.js 16 z włączonym Cache Components opcja fetchCache znika na rzecz dyrektywy 'use cache'.
Migracja istniejącego projektu
Krok 1: Włącz typedRoutes
Migracja zaczyna się od tej samej zmiany w konfiguracji co w nowym projekcie:
// next.config.js
module.exports = {
typedRoutes: true,
};Po zapisaniu pliku nic się jeszcze nie psuje, bo typy tras nie są jeszcze wygenerowane.
Krok 2: Uruchom build lub dev
Typy powstają przy uruchomieniu serwera deweloperskiego lub budowania:
npm run dev
# lub
npm run buildMożesz też użyć next typegen, które generuje typy bez uruchamiania serwera.
Krok 3: Napraw błędy TypeScript
Teraz sprawdź typy w całym projekcie. Skrypt type-check to zwykle tsc --noEmit dodany w package.json:
# Sprawdź błędy
npm run type-check
# Typowe problemy:
# - Literówki w ścieżkach
# - Nieistniejące strony
# - Zewnętrzne linki w <Link>Każdy zgłoszony błąd to realny link, który prowadziłby donikąd.
Debugowanie
Jeśli typy nie działają poprawnie, usuń wygenerowane pliki i pozwól Next.js utworzyć je od nowa:
# Usuń wygenerowane typy i wygeneruj ponownie
rm -rf .next/types
npm run devSprawdź wygenerowany plik w katalogu .next/types. W starszych wersjach nazywał się link.d.ts, nowsze wydania mogą używać innej nazwy:
// .next/types/link.d.ts
// Ten plik zawiera wszystkie wygenerowane typy RouteNext.js generuje tam też globalne pomocniki PageProps, LayoutProps i RouteContext, które typują parametry stron według ścieżki. Nie edytuj tych plików ręcznie, bo zostaną nadpisane.
Podsumowanie
Typed Routes w Next.js zapewniają:
- Bezpieczeństwo typów - błędy w ścieżkach wykryte w compile-time
- Autocomplete - IDE podpowiada dostępne ścieżki
- Refactoring - zmiana struktury routingu automatycznie pokazuje błędy
- Dokumentacja - typy służą jako dokumentacja dostępnych ścieżek
Moja rada: włącz typedRoutes na starcie projektu i trzymaj wszystkie linki nawigacji w tablicach typu Route. W następnej lekcji poznasz next-intl, gdzie ścieżki dostaną jeszcze prefiks języka.
Zapamiętaj: w Metropolii Quantum każdy kurs jest sprawdzany przed startem, a Typed Routes zamieniają zepsuty link w błąd kompilacji.
Kod do tej lekcji: App.tsx
// Demo: Typed Routes - bezpieczne linki z TypeScript
// Next.js experimental typedRoutes zapewnia type-safety dla Link i router
import React, { useState } from 'react';
// Konfiguracja w next.config.js:
// /** @type {import('next').NextConfig} */
// const nextConfig = {
// experimental: {
// typedRoutes: true,
// },
// };
//
// Po włączeniu Next.js generuje typy w .next/types:
// - Link href jest type-checked
// - router.push() wymaga prawidłowej ścieżki
// - Błędy kompilacji przy nieistniejących trasach
interface Route {
path: string;
params?: Record<string, string>;
description: string;
valid: boolean;
component: string;
}
const routes: Route[] = [
{ path: '/', description: 'Home page', valid: true, component: 'app/page.tsx' },
{ path: '/products', description: 'Products listing', valid: true, component: 'app/products/page.tsx' },
{ path: '/products/neural-link', description: 'Product detail (slug)', valid: true, component: 'app/products/[slug]/page.tsx', params: { slug: 'neural-link' } },
{ path: '/dashboard', description: 'User dashboard', valid: true, component: 'app/dashboard/page.tsx' },
{ path: '/dashboard/settings', description: 'Dashboard settings', valid: true, component: 'app/dashboard/settings/page.tsx' },
{ path: '/api/health', description: 'Health check endpoint', valid: true, component: 'app/api/health/route.ts' },
{ path: '/nonexistent', description: 'This route does not exist!', valid: false, component: '???' },
{ path: '/dashbord', description: 'Typo in route name!', valid: false, component: '???' },
];
function TypedLinkExample({ route }: { route: Route }) {
return (
<div style={{
background: route.valid ? 'rgba(100,255,218,0.05)' : 'rgba(244,67,54,0.05)',
border: `1px solid ${route.valid ? 'rgba(100,255,218,0.15)' : 'rgba(244,67,54,0.2)'}`,
borderRadius: '8px', padding: '14px', marginBottom: '8px',
}}>
<div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center' }}>
<div>
<code style={{
color: route.valid ? '#64ffda' : '#f44336',
fontSize: '0.9rem',
}}>
<Link href="{route.path}">
</code>
{route.params && (
<span style={{ color: '#ff9800', fontSize: '0.75rem', marginLeft: '8px' }}>
params: {JSON.stringify(route.params)}
</span>
)}
</div>
<span style={{
background: route.valid ? 'rgba(76,175,80,0.15)' : 'rgba(244,67,54,0.15)',
color: route.valid ? '#4caf50' : '#f44336',
padding: '2px 10px', borderRadius: '10px', fontSize: '0.7rem',
}}>
{route.valid ? 'Type OK' : 'Type Error'}
</span>
</div>
<div style={{ display: 'flex', justifyContent: 'space-between', marginTop: '6px' }}>
<span style={{ color: '#78909c', fontSize: '0.8rem' }}>{route.description}</span>
<code style={{ color: '#78909c', fontSize: '0.7rem' }}>{route.component}</code>
</div>
{!route.valid && (
<div style={{
marginTop: '8px', padding: '8px',
background: 'rgba(244,67,54,0.08)', borderRadius: '4px',
fontFamily: 'monospace', fontSize: '0.75rem', color: '#f44336',
}}>
Type error: Type '"{route.path}"' is not assignable to type 'Route'.
</div>
)}
</div>
);
}
function CodeComparison() {
return (
<div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: '12px', marginTop: '20px' }}>
<div style={{
background: 'rgba(244,67,54,0.05)', border: '1px solid rgba(244,67,54,0.15)',
borderRadius: '10px', padding: '16px',
}}>
<h4 style={{ color: '#f44336', marginBottom: '8px', fontSize: '0.85rem' }}>
Bez Typed Routes
</h4>
<pre style={{ margin: 0, color: '#b0bec5', fontSize: '0.75rem', lineHeight: 1.6 }}>
{
`// Brak weryfikacji w compile-time
<Link href="/dashbord"> // Typo!
<Link href="/old-page"> // Nie istnieje!
// Błąd odkryty dopiero w runtime
// 404 page, zła nawigacja...`}
</pre>
</div>
<div style={{
background: 'rgba(76,175,80,0.05)', border: '1px solid rgba(76,175,80,0.15)',
borderRadius: '10px', padding: '16px',
}}>
<h4 style={{ color: '#4caf50', marginBottom: '8px', fontSize: '0.85rem' }}>
Z Typed Routes
</h4>
<pre style={{ margin: 0, color: '#b0bec5', fontSize: '0.75rem', lineHeight: 1.6 }}>
{
`// TypeScript sprawdza w compile-time
<Link href="/dashbord"> // TS Error!
// Type '"/dashbord"' is not
// assignable to type 'Route'
<Link href="/dashboard"> // OK!
router.push("/products") // OK!`}
</pre>
</div>
</div>
);
}
export default function TypedRoutesDemo() {
const [showAll, setShowAll] = useState(true);
const displayed = showAll ? routes : routes.filter(r => !r.valid);
return (
<div style={{
background: '#0f0f23', minHeight: '100vh', padding: '24px',
color: '#fff', fontFamily: 'system-ui, sans-serif',
}}>
<h1 style={{ color: '#64ffda', marginBottom: '4px' }}>Typed Routes</h1>
<p style={{ color: '#b0bec5', marginBottom: '20px' }}>
Bezpieczne linki z TypeScript - błędy wychwycone w compile-time
</p>
<div style={{
background: 'rgba(0,0,0,0.3)', borderRadius: '8px',
padding: '12px', marginBottom: '20px',
}}>
<code style={{ color: '#78909c', fontSize: '0.8rem' }}>
// next.config.js
</code>
<br />
<code style={{ color: '#64ffda', fontSize: '0.8rem' }}>
experimental: {'{'} typedRoutes: true {'}'}
</code>
</div>
<div style={{ display: 'flex', gap: '8px', marginBottom: '16px' }}>
<button onClick={() => setShowAll(true)} style={{
background: showAll ? '#64ffda' : 'transparent',
color: showAll ? '#0f0f23' : '#b0bec5',
border: '1px solid rgba(100,255,218,0.3)',
padding: '6px 14px', borderRadius: '20px', cursor: 'pointer',
}}>All Routes</button>
<button onClick={() => setShowAll(false)} style={{
background: !showAll ? '#f44336' : 'transparent',
color: !showAll ? '#fff' : '#b0bec5',
border: '1px solid rgba(255,255,255,0.1)',
padding: '6px 14px', borderRadius: '20px', cursor: 'pointer',
}}>Type Errors Only</button>
</div>
{displayed.map(r => (
<TypedLinkExample key={r.path} route={r} />
))}
<CodeComparison />
</div>
);
}Hasła z dokumentacji w tej lekcji
Widzisz błąd w tej lekcji?
Sprawdź się
Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.
1. Typed Routes w Next.js zapewniają:
Zadania praktyczne w grze
- Układanie w poziomie
Ułóż elementy w prawidłowej kolejności: export const → fetchCache → =