Kurs Next.js · Moduł 9: Integracje i zaawansowane funkcje

Typed Routes - Bezpieczne linki z TypeScript

8 min czytania ·
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

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>  // OK

TypeScript 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');  // Error

Funkcja 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ę.

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>  // OK

Sprawdzany 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 build

Moż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 dev

Sprawdź 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 Route

Next.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',
          }}>
            &lt;Link href="{route.path}"&gt;
          </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. 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 → =

  1. PytanieTyped Routes w Next.js
  2. Ułóż w kolejnościKolejność: export const → fetchCache → =

Przydatne artykuły