Kurs Next.js · Moduł 2: Routing i layouty
Grupowanie i organizacja tras
W tej lekcji6
W sercu Metropolii Quantum system zarządzania przestrzenią miejską opiera się na koncepcji dzielnic tematycznych i stref funkcjonalnych. Miasto podzielone jest na rozpoznawalne obszary - dzielnicę naukową, strefę mieszkalną, dzielnicę rozrywkową i wiele innych. Te strefy są od siebie oddzielone, ale współdziałają jako elementy jednego, spójnego organizmu miejskiego.
W podobny sposób w Next.js 16 możemy organizować i grupować trasy naszej aplikacji, aby zwiększyć przejrzystość kodu, usprawnić zarządzanie i umożliwić bardziej elastyczne strategie ładowania i izolacji komponentów.
Grupy tras (Route Groups)
W App Routerze możemy tworzyć grupy tras, które nie mają wpływu na faktyczną strukturę URL, umieszczając katalog w nawiasach, na przykład: (nazwaGrupy). To potężna funkcja, która pozwala na logiczne organizowanie kodu bez zmiany jego zachowania czy publicznego API.
Struktura i składnia grup tras
Grupy tras są definiowane przez umieszczenie nazwy katalogu w nawiasach:
app/
├── (marketing)/ # Grupa dla stron marketingowych
│ ├── about/
│ │ └── page.tsx # /about
│ ├── blog/
│ │ └── page.tsx # /blog
│ └── layout.tsx # Współdzielony układ dla stron marketingowych
│
├── (shop)/ # Grupa dla stron sklepowych
│ ├── products/
│ │ └── page.tsx # /products
│ ├── cart/
│ │ └── page.tsx # /cart
│ └── layout.tsx # Współdzielony układ dla stron sklepowych
│
└── layout.tsx # Główny układ aplikacjiW tym przykładzie trasy /about i /blog są częścią grupy (marketing), podczas gdy /products i /cart są częścią grupy (shop). Zauważ, że grupy tras nie wpływają na faktyczne URL-e - katalog (marketing) nie jest częścią ścieżki URL /about.
Zastosowania grup tras
1. Organizacja plików i folderów
Najprostszym zastosowaniem grup tras jest logiczna organizacja plików, zwłaszcza w większych aplikacjach:
app/
├── (main)/ # Główne strony publiczne
│ ├── page.tsx # Strona główna (/)
│ ├── about/ # /about
│ └── contact/ # /contact
│
├── (auth)/ # Strony związane z uwierzytelnianiem
│ ├── login/ # /login
│ ├── register/ # /register
│ └── forgot-password/ # /forgot-password
│
├── (dashboard)/ # Strony dashboardu (chronione)
│ ├── account/ # /account
│ ├── settings/ # /settings
│ └── billing/ # /billing
│
└── layout.tsx # Główny układ2. Współdzielenie układów między określonymi trasami
Jednym z najpotężniejszych zastosowań grup tras jest możliwość definiowania wspólnych układów dla określonych grup stron bez wpływu na ścieżki URL:
// app/(marketing)/layout.tsx - Układ dla stron marketingowych
export default function MarketingLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<div className="marketing-layout">
<nav className="marketing-nav">
<a href="/about">O nas</a>
<a href="/blog">Blog</a>
<a href="/careers">Kariera</a>
</nav>
<main>{children}</main>
<footer className="marketing-footer">
<p>© 2150 Quantum Voyages. Wszystkie prawa zastrzeżone.</p>
</footer>
</div>
);
}// app/(shop)/layout.tsx - Układ dla stron sklepowych
export default function ShopLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<div className="shop-layout">
<header className="shop-header">
<h1>Quantum Voyages Store</h1>
<nav className="shop-nav">
<a href="/products">Produkty</a>
<a href="/categories">Kategorie</a>
<a href="/cart">Koszyk</a>
</nav>
</header>
<main>{children}</main>
<aside className="shop-sidebar">
<div className="popular-products">
<h3>Popularne produkty</h3>
{/* Lista popularnych produktów */}
</div>
</aside>
</div>
);
}3. Rozdzielanie aplikacji na sekcje
Grupy tras są szczególnie przydatne w aplikacjach wielosekcyjnych, takich jak aplikacja z publiczną stroną główną, panelem administracyjnym i dashboardem użytkownika:
app/
├── (public)/ # Publiczna część witryny
│ ├── page.tsx # Strona główna (/)
│ ├── about/ # /about
│ ├── blog/ # /blog
│ │ └── [slug]/ # /blog/:slug
│ └── layout.tsx # Układ publiczny
│
├── (admin)/ # Panel administracyjny
│ ├── admin/ # /admin (uwaga: potrzebny katalog admin/ dla zachowania URL)
│ │ ├── page.tsx # /admin
│ │ ├── users/ # /admin/users
│ │ └── settings/ # /admin/settings
│ └── layout.tsx # Układ admin
│
├── (dashboard)/ # Dashboard użytkownika
│ ├── dashboard/ # /dashboard
│ │ ├── page.tsx # /dashboard
│ │ ├── profile/ # /dashboard/profile
│ │ └── settings/ # /dashboard/settings
│ └── layout.tsx # Układ dashboard
│
└── layout.tsx # Główny układ (wspólny dla wszystkich sekcji)W tym przykładzie aplikacja jest podzielona na trzy główne sekcje, każda z własnym układem, ale wszystkie dzielą wspólny układ główny.
Przykład dla Quantum Voyages
Zaimplementujmy system grup tras dla naszej kosmicznej aplikacji Quantum Voyages:
app/
├── (marketing)/ # Strony marketingowe
│ ├── page.tsx # Strona główna (/)
│ ├── about/ # /about
│ ├── destinations/ # /destinations
│ │ └── [id]/ # /destinations/:id
│ └── layout.tsx # Układ marketingowy
│
├── (customer)/ # Strony dla zalogowanych klientów
│ ├── dashboard/ # /dashboard
│ ├── bookings/ # /bookings
│ │ └── [id]/ # /bookings/:id
│ ├── account/ # /account
│ └── layout.tsx # Układ dla klientów
│
├── (admin)/ # Panel administracyjny
│ ├── admin/ # /admin
│ │ ├── voyages/ # /admin/voyages
│ │ ├── customers/ # /admin/customers
│ │ └── analytics/ # /admin/analytics
│ └── layout.tsx # Układ administracyjny
│
└── layout.tsx # Główny układKod dla układów:
// app/layout.tsx - Główny układ
import { Inter } from 'next/font/google';
import './globals.css';
const inter = Inter({ subsets: ['latin'] });
export const metadata = {
title: 'Quantum Voyages - Podróże kosmiczne z Metropolii Quantum',
description: 'Odkryj kosmos z przewodnikiem po Metropolii Quantum',
};
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<html lang="pl">
<body className={inter.className}>
{children}
</body>
</html>
);
}// app/(marketing)/layout.tsx - Układ marketingowy
import Header from '@/components/marketing/Header';
import Footer from '@/components/marketing/Footer';
export default function MarketingLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<>
<Header />
<main className="min-h-screen pt-16 pb-20">
{children}
</main>
<Footer />
</>
);
}// app/(customer)/layout.tsx - Układ dla zalogowanych klientów
import CustomerHeader from '@/components/customer/Header';
import CustomerSidebar from '@/components/customer/Sidebar';
import { checkAuth } from '@/lib/auth';
import { redirect } from 'next/navigation';
export default async function CustomerLayout({
children,
}: {
children: React.ReactNode;
}) {
// Sprawdzenie, czy użytkownik jest zalogowany
const user = await checkAuth();
if (!user) {
// Layout to Server Component: nie ma tu obiektu window. Adres powrotu może dopisać proxy.ts.
redirect('/login');
}
return (
<>
<CustomerHeader user={user} />
<div className="flex min-h-screen pt-16">
<CustomerSidebar />
<main className="flex-1 p-6 bg-gray-50">
{children}
</main>
</div>
</>
);
}// app/(admin)/layout.tsx - Układ administracyjny
import AdminHeader from '@/components/admin/Header';
import AdminSidebar from '@/components/admin/Sidebar';
import { checkAdminAuth } from '@/lib/auth';
import { redirect } from 'next/navigation';
export default async function AdminLayout({
children,
}: {
children: React.ReactNode;
}) {
// Sprawdzenie, czy użytkownik jest administratorem
const isAdmin = await checkAdminAuth();
if (!isAdmin) {
redirect('/admin-login');
}
return (
<div className="admin-layout">
<AdminHeader />
<div className="flex min-h-screen pt-16">
<AdminSidebar />
<main className="flex-1 p-6 bg-gray-100">
{children}
</main>
</div>
</div>
);
}Grupy tylko do porządkowania plików
Grupa tras nie musi mieć własnego layout.tsx. Możesz jej użyć wyłącznie po to, by uporządkować pliki, a adresy URL zostaną takie same:
app/
├── (onboarding)/welcome/
│ └── page.tsx # /welcome
└── (payments)/cart/
└── page.tsx # /cartSeparowanie układów i ścieżek URL
Grupy tras są szczególnie przydatne, gdy chcemy współdzielić układ między specyficznymi trasami, które niekoniecznie są blisko siebie w hierarchii URL:
app/
├── (auth)/
│ ├── login/ # /login
│ │ └── page.tsx
│ ├── register/ # /register
│ │ └── page.tsx
│ └── layout.tsx # Układ współdzielony tylko dla /login i /register
│
├── account/ # /account (nie używa układu (auth))
│ └── page.tsx
│
└── layout.tsx # Główny układ dla wszystkich trasPrywatne foldery (_folderName)
Next.js 16 obsługuje również konwencję prywatnych folderów, które są oznaczone podkreślnikiem (_) na początku nazwy. Takie foldery nie są uwzględniane w ścieżkach URL, ale mogą zawierać kod współdzielony przez wiele tras.
Struktura i składnia prywatnych folderów
app/
├── _components/ # Prywatny folder dla komponentów współdzielonych
│ ├── Button.tsx # Komponent przycisku
│ ├── Card.tsx # Komponent karty
│ └── SearchForm.tsx # Komponent formularza wyszukiwania
│
├── _lib/ # Prywatny folder dla współdzielonych funkcji
│ ├── api.ts # Funkcje API
│ └── utils.ts # Funkcje narzędziowe
│
├── destinations/ # Publiczna trasa
│ └── page.tsx # /destinations
│
└── page.tsx # Strona główna (/)W tym przykładzie katalogi _components i _lib są prywatne i nie generują żadnych ścieżek URL. Są one używane do przechowywania współdzielonych komponentów i funkcji, które mogą być importowane przez inne komponenty.
Różnica między prywatnymi folderami a grupami tras
Prywatne foldery i grupy tras wyglądają podobnie, ale mają różne zastosowania:
- Prywatne foldery (
_folderName) są używane do organizowania kodu, który nie powinien być bezpośrednio dostępny przez URL. - Grupy tras (
(folderName)) są używane do grupowania tras bez wpływu na ścieżki URL, ale mogą wpływać na zachowanie układów.
Przykład zastosowania prywatnych folderów w aplikacji Quantum Voyages
app/
├── _components/ # Współdzielone komponenty UI
│ ├── ui/ # Podstawowe komponenty UI
│ │ ├── Button.tsx
│ │ ├── Card.tsx
│ │ └── Input.tsx
│ │
│ ├── marketing/ # Komponenty dla stron marketingowych
│ │ ├── HeroSection.tsx
│ │ └── TestimonialCard.tsx
│ │
│ └── bookings/ # Komponenty dla systemu rezerwacji
│ ├── BookingForm.tsx
│ └── PlanetSelector.tsx
│
├── _lib/ # Współdzielone funkcje i utilities
│ ├── api/ # Funkcje do komunikacji z API
│ │ ├── destinations.ts
│ │ └── bookings.ts
│ │
│ ├── hooks/ # Własne hooki React
│ │ ├── useBooking.ts
│ │ └── useAuth.ts
│ │
│ └── utils/ # Funkcje pomocnicze
│ ├── dates.ts
│ └── validation.ts
│
├── _data/ # Dane statyczne (można też użyć /public)
│ ├── destinations.json
│ └── testimonials.json
│
├── (marketing)/ # Grupa dla stron marketingowych
│ ├── page.tsx # Strona główna (/)
│ ├── about/ # /about
│ └── destinations/ # /destinations
│
└── (customer)/ # Grupa dla stron klienta
├── dashboard/ # /dashboard
└── bookings/ # /bookingsPrzykład kodu z wykorzystaniem prywatnych folderów:
// app/_components/ui/Button.tsx
import { cva, type VariantProps } from 'class-variance-authority';
import { cn } from '@/app/_lib/utils/cn';
const buttonVariants = cva(
'inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2',
{
variants: {
variant: {
default: 'bg-primary text-primary-foreground hover:bg-primary/90',
destructive: 'bg-destructive text-destructive-foreground hover:bg-destructive/90',
outline: 'border border-input bg-background hover:bg-accent hover:text-accent-foreground',
secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
ghost: 'hover:bg-accent hover:text-accent-foreground',
link: 'text-primary underline-offset-4 hover:underline',
},
size: {
default: 'h-10 px-4 py-2',
sm: 'h-9 rounded-md px-3',
lg: 'h-11 rounded-md px-8',
icon: 'h-10 w-10',
},
},
defaultVariants: {
variant: 'default',
size: 'default',
},
}
);
export interface ButtonProps
extends React.ButtonHTMLAttributes<HTMLButtonElement>,
VariantProps<typeof buttonVariants> {
asChild?: boolean;
}
export function Button({
className,
variant,
size,
asChild = false,
...props
}: ButtonProps) {
return (
<button
className={cn(buttonVariants({ variant, size, className }))}
{...props}
/>
);
}// app/(marketing)/destinations/page.tsx
import { getDestinations } from '@/app/_lib/api/destinations';
import DestinationCard from '@/app/_components/marketing/DestinationCard';
import { HeroSection } from '@/app/_components/marketing/HeroSection';
export default async function DestinationsPage() {
const destinations = await getDestinations();
return (
<div className="container mx-auto px-4 py-12">
<HeroSection
title="Odkryj kosmos z Quantum Voyages"
subtitle="Przeglądaj nasze kosmiczne destynacje i zaplanuj swoją przygodę"
image="/images/space-banner.jpg"
/>
<section className="my-12">
<h2 className="text-3xl font-bold mb-8">Popularne destynacje</h2>
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-8">
{destinations.map((destination) => (
<DestinationCard
key={destination.id}
destination={destination}
/>
))}
</div>
</section>
</div>
);
}Pliki routingu (route.js)
Next.js 16 umożliwia tworzenie API endpoints przy użyciu plików route.js (lub route.ts). Również dla tych plików możemy stosować techniki organizacyjne, takie jak grupy tras i prywatne foldery.
Organizacja API endpoints
app/
├── api/ # Główna sekcja API
│ ├── (public)/ # Publiczne endpointy
│ │ ├── destinations/
│ │ │ └── route.ts # GET /api/destinations
│ │ └── newsletter/
│ │ └── route.ts # POST /api/newsletter
│ │
│ ├── (protected)/ # Chronione endpointy (wymagają autoryzacji)
│ │ ├── bookings/
│ │ │ ├── route.ts # GET, POST /api/bookings
│ │ │ └── [id]/
│ │ │ └── route.ts # GET, PUT, DELETE /api/bookings/:id
│ │ └── user/
│ │ └── route.ts # GET /api/user
│ │
│ └── _middleware/ # Middleware dla API (prywatny folder)
│ ├── auth.ts # Middleware uwierzytelniania
│ └── rateLimit.ts # Middleware ograniczenia liczby zapytań
│
└── page.tsx # Strona główna (/)Przykład implementacji chronionego endpointu API:
// app/api/(protected)/bookings/route.ts
import { NextResponse } from 'next/server';
import { verifyAuth } from '@/app/api/_middleware/auth';
import { rateLimit } from '@/app/api/_middleware/rateLimit';
export async function GET(request: Request) {
// Weryfikacja uwierzytelnienia
const authResult = await verifyAuth(request);
if (!authResult.isAuthenticated) {
return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
}
// Ograniczenie liczby zapytań
const rateLimitResult = await rateLimit(request);
if (!rateLimitResult.success) {
return NextResponse.json({ error: 'Too many requests' }, { status: 429 });
}
// Pobranie rezerwacji dla zalogowanego użytkownika
const userId = authResult.user.id;
const bookings = await getBookingsForUser(userId);
return NextResponse.json({ bookings });
}
export async function POST(request: Request) {
// Weryfikacja uwierzytelnienia
const authResult = await verifyAuth(request);
if (!authResult.isAuthenticated) {
return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
}
// Parsowanie danych z żądania
const data = await request.json();
// Walidacja danych
const validationResult = validateBookingData(data);
if (!validationResult.success) {
return NextResponse.json({ error: validationResult.errors }, { status: 400 });
}
// Tworzenie rezerwacji
const userId = authResult.user.id;
const booking = await createBooking(userId, data);
return NextResponse.json({ booking }, { status: 201 });
}Najlepsze praktyki organizacji tras w dużych aplikacjach
W Metropolii Quantum szczegółowe planowanie jest kluczowe dla efektywnego funkcjonowania miasta. Podobnie w większych aplikacjach Next.js 16 ważne jest przestrzeganie określonych zasad i wzorców organizacji tras:
1. Używaj jasnej i konsekwentnej struktury
Utrzymuj konsekwentną strukturę katalogów i nazewnictwo w całej aplikacji:
app/
├── (sections)/ # Grupy dla głównych sekcji
│ ├── (marketing)/ # Publiczna część
│ ├── (app)/ # Główna aplikacja
│ └── (admin)/ # Panel admina
│
├── _lib/ # Współdzielony kod
│ ├── components/ # Współdzielone komponenty
│ ├── hooks/ # Hooki React
│ └── utils/ # Funkcje narzędziowe
│
├── api/ # Endpointy API
│ ├── (public)/
│ └── (protected)/
│
└── layout.tsx # Główny układ2. Współdziel komponenty mądrze
Używaj prywatnych folderów do przechowywania współdzielonych komponentów i umieszczaj je na odpowiednim poziomie hierarchii:
- Komponenty używane w całej aplikacji:
app/_components/ - Komponenty specyficzne dla sekcji:
app/(section)/_components/
3. Stosuj rozdzielenie odpowiedzialności
page.js- Renderowanie strony i pobieranie danychlayout.js- Układ UI i logika nawigacjiloading.js- Stany ładowaniaerror.js- Obsługa błędównot-found.js- Obsługa zasobów nie znalezionych
4. Używaj aliasów importów w tsconfig.json/jsconfig.json
Skonfiguruj aliasy importów dla uproszczenia ścieżek:
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/*": ["./*"],
"@components/*": ["./app/_components/*"],
"@lib/*": ["./app/_lib/*"],
"@hooks/*": ["./app/_lib/hooks/*"],
"@utils/*": ["./app/_lib/utils/*"]
}
}
}Dzięki temu możesz importować komponenty w bardziej czytelny sposób:
// Zamiast:
import { Button } from '../../../_components/ui/Button';
// Możesz użyć:
import { Button } from '@components/ui/Button';5. Implementacja dla aplikacji Quantum Voyages
Przykład kompleksowej struktury dla dużej aplikacji Quantum Voyages:
app/
├── (public)/ # Publiczna część witryny
│ ├── _components/ # Komponenty specyficzne dla części publicznej
│ ├── page.tsx # Strona główna (/)
│ ├── about/ # /about
│ ├── destinations/ # /destinations
│ │ ├── page.tsx # Lista destynacji
│ │ └── [id]/ # /destinations/:id
│ │ └── page.tsx # Szczegóły destynacji
│ ├── contact/ # /contact
│ └── layout.tsx # Układ publiczny
│
├── (auth)/ # Sekcja uwierzytelniania
│ ├── _components/ # Komponenty uwierzytelniania
│ ├── _lib/ # Logika uwierzytelniania
│ ├── login/ # /login
│ ├── register/ # /register
│ ├── forgot-password/ # /forgot-password
│ └── layout.tsx # Układ uwierzytelniania
│
├── (app)/ # Główna aplikacja (dla zalogowanych)
│ ├── _components/ # Komponenty aplikacji
│ ├── dashboard/ # /dashboard
│ ├── bookings/ # /bookings
│ │ ├── page.tsx # Lista rezerwacji
│ │ ├── new/ # /bookings/new
│ │ └── [id]/ # /bookings/:id
│ │ ├── page.tsx # Szczegóły rezerwacji
│ │ └── edit/ # /bookings/:id/edit
│ ├── account/ # /account
│ │ ├── page.tsx # Przegląd konta
│ │ ├── profile/ # /account/profile
│ │ └── preferences/ # /account/preferences
│ └── layout.tsx # Układ aplikacji
│
├── (admin)/ # Panel administracyjny
│ ├── _components/ # Komponenty admina
│ ├── admin/ # /admin (potrzebny folder dla URL)
│ │ ├── page.tsx # Dashboard admina
│ │ ├── users/ # /admin/users
│ │ ├── destinations/ # /admin/destinations
│ │ └── bookings/ # /admin/bookings
│ └── layout.tsx # Układ admina
│
├── _components/ # Współdzielone komponenty
│ ├── ui/ # Podstawowe komponenty UI
│ └── forms/ # Komponenty formularzy
│
├── _lib/ # Współdzielone funkcje
│ ├── api/ # Funkcje API
│ ├── hooks/ # Własne hooki
│ └── utils/ # Funkcje narzędziowe
│
├── api/ # Endpointy API
│ ├── (public)/ # Publiczne API
│ └── (protected)/ # Chronione API
│
└── layout.tsx # Główny układPodsumowanie
Grupowanie i organizacja tras w Next.js 16 oferuje wiele możliwości strukturyzowania aplikacji w logiczny i przejrzysty sposób, podobnie jak strefowanie urbanistyczne w Metropolii Quantum organizuje przestrzeń miejską dla maksymalnej wydajności i funkcjonalności.
Kluczowe koncepcje:
Grupy tras (
(groupName)) - pozwalają na logiczne grupowanie tras bez wpływu na ścieżki URL, co jest szczególnie przydatne do dzielenia różnych sekcji aplikacji i implementacji specyficznych układów.Prywatne foldery (
_folderName) - umożliwiają organizację kodu, współdzielonych komponentów i funkcji, które nie są bezpośrednio dostępne przez URL.Hierarchiczne układy - możliwość definiowania specyficznych układów dla różnych grup tras, zapewniając spójne doświadczenie użytkownika w ramach każdej sekcji.
Organizacja API - stosowanie tych samych zasad organizacji dla endpointów API.
Dzięki tym technikom można tworzyć aplikacje, które są:
- Bardziej przejrzyste i łatwiejsze w utrzymaniu
- Elastyczne w zakresie nawigacji i doświadczenia użytkownika
- Dobrze zorganizowane dla zespołów deweloperskich
- Skalowalne dla rozwijających się aplikacji
W następnym rozdziale odkryjemy, jak obsługiwać bardziej złożone scenariusze nawigacji, takie jak trasy zagnieżdżone i parametry catch-all, które umożliwiają tworzenie zaawansowanych i elastycznych systemów nawigacji w aplikacjach Next.js 16.
Hasła z dokumentacji w tej lekcji
Widzisz błąd w tej lekcji?