Przejdź do treści

Jak organizować kod w dużych projektach Next.js?

Maciej Sala

Founder StriveLab

7 min czytaniaAktualizacja

Szybka odpowiedź: jak organizować kod w dużym projekcie Next.js?

  • Grupuj kod według domen biznesowych, np. features/invoices, a nie według typów plików.
  • Katalog app/ traktuj jako warstwę tras i kompozycji, a shared/ tylko na naprawdę generyczny kod.
  • Każdy moduł ma jawne publiczne wejścia, osobno dla kodu serwerowego i klienckiego.
  • Granice importów pilnuj regułą no-restricted-imports, a cykle sprawdzaj osobną analizą grafu zależności w CI.
  • W małym projekcie zacznij prosto, a w razie potrzeby refaktoryzuj domena po domenie.

Problem: nieuporządkowane katalogi utrudniają rozwój dużego projektu

Next.js nie narzuca podziału na domeny. Zarówno kolokacja w app/, jak i osobne features/ mogą działać w dużym projekcie — problemem są niejasne granice i zależności, a nie sam wybór katalogów.

Typowe objawy:

  • Folder components/ z 80 plikami, gdzie Button.tsx leży obok InvoiceCalculator.tsx
  • lib/ jako worek na wszystko — od funkcji formatujących daty po logikę płatności
  • Zależności krzyżowe — komponent koszyka importuje coś z modułu użytkownika, który importuje coś z koszyka
  • Nikt w zespole nie wie, gdzie dodać nowy plik

Architektura modułowa w Next.js: główna zasada organizacyjna

Podstawą porządku jest (ang. feature-based architecture, czasem opisywana jako domain-driven folder structure), która grupuje kod według funkcjonalności biznesowej, nie według typu technicznego.

Zamiast:

Code
components/
├── Button.tsx
├── Card.tsx
├── InvoiceForm.tsx
├── InvoiceList.tsx
├── ProductCard.tsx
├── ProductGrid.tsx
├── UserAvatar.tsx
└── UserProfile.tsx

Masz:

Code
features/
├── invoices/
│   ├── components/
│   ├── hooks/
│   ├── actions/
│   └── types.ts
├── products/
│   ├── components/
│   ├── hooks/
│   ├── actions/
│   └── types.ts
└── users/
    ├── components/
    ├── hooks/
    ├── actions/
    └── types.ts

Każdy moduł to możliwie spójna całość z własnymi komponentami, hookami, akcjami serwerowymi, typami i testami. Nie musi być całkowicie niezależny, ale jego zależności powinny być jawne, jednokierunkowe i prowadzić wyłącznie przez dozwolone publiczne wejścia.

Struktura projektu Next.js App Router w architekturze modułowej

Code
src/
├── app/                          ← Trasy, layouty i kompozycja
│   ├── layout.tsx
│   ├── (marketing)/              ← Route group — strony marketingowe
│   │   ├── layout.tsx
│   │   ├── page.tsx
│   │   └── cennik/
│   │       └── page.tsx
│   ├── (dashboard)/              ← Route group — panel
│   │   ├── layout.tsx
│   │   ├── dashboard/
│   │   │   └── page.tsx
│   │   ├── invoices/
│   │   │   ├── page.tsx
│   │   │   └── [id]/
│   │   │       └── page.tsx
│   │   └── products/
│   │       └── page.tsx
│   └── api/
│       └── webhooks/
│           └── stripe/
│               └── route.ts
│
├── features/                     ← Logika biznesowa
│   ├── auth/
│   │   ├── components/
│   │   │   ├── login-form.tsx
│   │   │   ├── register-form.tsx
│   │   │   └── auth-provider.tsx
│   │   ├── actions/
│   │   │   ├── login.ts
│   │   │   └── register.ts
│   │   ├── hooks/
│   │   │   └── use-session.ts
│   │   ├── lib/
│   │   │   ├── auth-config.ts
│   │   │   └── session.ts
│   │   ├── types.ts
│   │   ├── server.ts             ← Publiczne funkcje sesji, import server-only
│   │   └── index.ts              ← Publiczne UI i typy
│   │
│   ├── invoices/
│   │   ├── components/
│   │   │   ├── invoice-form.tsx
│   │   │   ├── invoice-list.tsx
│   │   │   ├── invoice-card.tsx
│   │   │   └── invoice-status-badge.tsx
│   │   ├── actions/
│   │   │   ├── create-invoice.ts
│   │   │   ├── update-invoice.ts
│   │   │   └── delete-invoice.ts
│   │   ├── hooks/
│   │   │   └── use-invoice-filters.ts
│   │   ├── lib/
│   │   │   ├── invoice-calculations.ts
│   │   │   └── invoice-pdf.ts
│   │   ├── schemas/
│   │   │   └── create-invoice.ts
│   │   ├── types.ts
│   │   ├── server.ts             ← Publiczne wejście serwerowe
│   │   └── index.ts              ← Publiczne UI i typy
│   │
│   └── products/
│       ├── components/
│       ├── actions/
│       ├── hooks/
│       ├── lib/
│       ├── types.ts
│       └── index.ts
│
├── shared/                       ← Współdzielone zasoby
│   ├── components/               ← Generyczne komponenty UI
│   │   ├── ui/
│   │   │   ├── button.tsx
│   │   │   ├── card.tsx
│   │   │   ├── input.tsx
│   │   │   └── modal.tsx
│   │   └── layout/
│   │       ├── header.tsx
│   │       ├── footer.tsx
│   │       └── sidebar.tsx
│   ├── hooks/
│   │   ├── use-debounce.ts
│   │   └── use-media-query.ts
│   ├── lib/
│   │   ├── db.ts
│   │   ├── auth.ts
│   │   ├── formatters.ts
│   │   ├── validators.ts
│   │   └── constants.ts
│   └── types/
│       └── global.ts
│
└── config/                       ← Konfiguracja
    ├── navigation.ts
    └── site.ts

Cztery zasady architektury modułowej

1. app/ w Next.js jest warstwą tras i kompozycji

Next.js pozwala bezpiecznie kolokować w app/ komponenty, funkcje i testy — plik nie staje się trasą, dopóki segment nie zawiera page.tsx albo route.ts. Cienkie page.tsx i layout.tsx są dobrą konwencją w dużym projekcie, ale nie wymogiem frameworka. W app/ naturalnie zostają pliki specjalne Next.js, metadane oraz kod ściśle związany z daną trasą; logikę domenową wielokrotnego użytku przenoś do features/.

Code
// app/(dashboard)/invoices/page.tsx
import { InvoiceList } from '@/features/invoices'
import { getInvoices } from '@/features/invoices/server'
 
export default async function InvoicesPage() {
  const invoices = await getInvoices()
 
  return (
    <div>
      <h1>Faktury</h1>
      <InvoiceList invoices={invoices} />
    </div>
  )
}

2. Każdy moduł ma jawne publiczne wejścia

Moduł eksportuje przez tylko to, czego mogą używać inne moduły. W App Routerze jeden index.ts eksportujący jednocześnie komponenty klienckie, zapytania do bazy i Server Actions zaciera jednak granicę środowisk. Bezpieczniej rozdzielić publiczne wejścia, np. index.ts dla UI i typów, server.ts dla kodu serwerowego oraz osobne pliki akcji:

Code
// features/invoices/index.ts
// Public API — tylko te eksporty są dostępne na zewnątrz
 
// Komponenty
export { InvoiceList } from './components/invoice-list'
export { InvoiceForm } from './components/invoice-form'
export { InvoiceCard } from './components/invoice-card'
 
// Typy
export type { Invoice, InvoiceStatus, CreateInvoiceInput } from './types'
 
// NIE eksportuj:
// - invoice-calculations.ts (wewnętrzny helper)
// - invoice-status-badge.tsx (wewnętrzny komponent)
// - use-invoice-filters.ts (wewnętrzny hook)
Code
// features/invoices/server.ts
import 'server-only'
 
export { getInvoices, getInvoiceById } from './lib/queries'

Reguła importowania:

Code
// DOBRZE — import z public API
import { InvoiceList } from '@/features/invoices'
import { getInvoices } from '@/features/invoices/server'
import { createInvoice } from '@/features/invoices/actions/create-invoice'
 
// ŹLE — sięganie do wewnętrznych plików
import { InvoiceStatusBadge } from '@/features/invoices/components/invoice-status-badge'

'use client' wyznacza początek grafu modułów klienckich, więc importowane zależności mogą trafić do paczki JavaScriptu dla przeglądarki. Wyjątkiem są Server Functions importowane z plików z dyrektywą 'use server': klient otrzymuje referencję umożliwiającą wywołanie, a implementacja pozostaje na serwerze. Moduły z bazą, sekretami lub prywatnymi API oznaczaj przez import 'server-only'; dla kodu wymagającego window możesz analogicznie użyć client-only. Publiczne pliki zbiorcze (barrel files) są wygodne, ale po zmianach sprawdzaj ich wpływ na granice serwer–klient i rozmiar paczki.

3. Reguła zależności: jawny kierunek i brak cykli

Bezpośrednie importy między modułami ograniczaj do ich publicznych wejść. Jeśli scenariusz łączy kilka domen, składaj go w stronie albo osobnej warstwie aplikacyjnej zamiast tworzyć cykl invoices → users → invoices:

Code
// ŹLE — invoice sięga do prywatnego wnętrza auth
import { getCurrentUser } from '@/features/auth/lib/session'
 
// DOBRZE — page przekazuje dane jako prop
// app/(dashboard)/invoices/page.tsx
import { redirect } from 'next/navigation'
import { getCurrentUser } from '@/features/auth/server'
import { InvoiceList } from '@/features/invoices'
import { getInvoices } from '@/features/invoices/server'
 
export default async function InvoicesPage() {
  const user = await getCurrentUser()
  if (!user) redirect('/login')
 
  const invoices = await getInvoices({ userId: user.id })
 
  return <InvoiceList invoices={invoices} userName={user.name} />
}

W tym przykładzie auth/server.ts oznacz przez import 'server-only' i wyeksportuj z niego getCurrentUser. Funkcja może zwrócić null, dlatego strona obsługuje brak sesji przed odczytem user.id.

Sesja, autoryzacja techniczna, klient bazy i telemetria są zależnościami przekrojowymi. Jeśli korzysta z nich większość modułów, wydziel ich stabilne kontrakty do shared/ albo core/. Ekrany logowania i reguły biznesowe użytkownika nadal mogą pozostać osobnymi modułami.

4. shared/ to fundament architektury

Katalog shared/ przechowuje wyłącznie elementy, które spełniają trzy warunki:

  • Nie należą do żadnej konkretnej domeny biznesowej (np. Button, Modal, formatDate).

  • Są wykorzystywane przez co najmniej dwa niezależne moduły.

  • Nie zawierają logiki specyficznej dla żadnej domeny.

Jeśli dany komponent służy tylko jednej funkcjonalności, zostaje wewnątrz niej, nawet jeśli na pierwszy rzut oka wygląda na całkowicie generyczny.

Server Actions w architekturze modułowej

Code
// features/invoices/actions/create-invoice.ts
'use server'
 
import { requireUser } from '@/shared/lib/auth'
import { revalidatePath } from 'next/cache'
import { db } from '@/shared/lib/db'
import { createInvoiceSchema } from '../schemas/create-invoice'
 
export async function createInvoice(formData: FormData) {
  const user = await requireUser()
 
  const parsed = createInvoiceSchema.safeParse({
    clientName: formData.get('clientName'),
    amount: Number(formData.get('amount')),
    dueDate: formData.get('dueDate'),
  })
 
  if (!parsed.success) {
    return { error: 'Nieprawidłowe dane', details: parsed.error.flatten() }
  }
 
  await db.invoice.create({
    data: {
      ...parsed.data,
      userId: user.id,
      status: 'DRAFT',
    },
  })
 
  revalidatePath('/invoices')
  return { success: true }
}

Każda Server Action jest publicznie dostępnym endpointem HTTP, dlatego sama walidacja danych wejściowych nie zastępuje uwierzytelnienia i autoryzacji. Przed aktualizacją lub usunięciem rekordu zweryfikuj po stronie serwera, czy zalogowany użytkownik ma uprawnienia do modyfikacji tego konkretnego zasobu. Nigdy nie ufaj identyfikatorowi właściciela przesłanemu w FormData, ponieważ klient może go dowolnie podmienić. Dodatkowo oznacz klienta bazy danych oraz moduł sesji dyrektywą import 'server-only', dzięki czemu przypadkowe zaimportowanie ich do Client Componentu natychmiast przerwie build aplikacji.

Gdzie umieszczać testy?

Testy jednostkowe i integracyjne trzymaj blisko kodu modułu, np. obok pliku jako invoice-calculations.test.ts albo w lokalnym __tests__/. Ułatwia to przeniesienie lub usunięcie całej funkcjonalności. Testy przekrojowe obejmujące kilka modułów — zwłaszcza scenariusze przeglądarkowe — mogą pozostać w głównym tests/e2e/. Ważniejsza od wyboru jednego katalogu jest konsekwencja i rozdzielenie szybkich testów domeny od testów pełnej aplikacji.

Aliasy ścieżek w TypeScript dla dużego projektu Next.js

Aby importy były czytelne, skonfiguruj aliasy:

Code
// tsconfig.json
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"],
      "@/features/*": ["./src/features/*"],
      "@/shared/*": ["./src/shared/*"],
      "@/config/*": ["./src/config/*"]
    }
  }
}

W aplikacji budowanej przez Next.js alias @/* zwykle wystarcza; pozostałe wpisy są zbędne, bo pasują już do pierwszego wzorca. paths pomaga TypeScriptowi i bundlerowi rozwiązywać importy, ale TypeScript nie przepisuje tych ścieżek w emitowanym JavaScripcie. Nie używaj więc aliasów jako zamiennika prawdziwych pakietów w monorepo.

Jak egzekwować granice modułów w zespole?

Sama dokumentacja nie zatrzyma importu do prywatnego pliku. Dodaj do ESLinta regułę no-restricted-imports albo narzędzie analizujące graf zależności i uruchamiaj je w CI. no-restricted-imports ogranicza wskazane ścieżki statycznych importów i reeksportów; nie wykrywa samodzielnie cykli ani dynamicznych import(). Cykle sprawdzaj osobnym analizatorem grafu zależności, a granice serwer–klient zabezpieczaj m.in. przez server-only i build Next.js w CI. Test architektury jest szczególnie wartościowy po przenosinach plików, gdy automatyczny import IDE łatwo omija publiczne API.

Nie ukrywaj każdego cyklu przez przeniesienie kodu do shared/. Najpierw ustal, czy brakującym elementem jest kontrakt, zdarzenie domenowe albo warstwa orkiestracji. W przeciwnym razie shared/ szybko stanie się dawnym lib/ pod nową nazwą.

Kiedy wydzielić monorepo?

Folder features/ porządkuje jeden produkt wdrażany jako całość. Monorepo ma sens dopiero wtedy, gdy kilka aplikacji lub usług rzeczywiście współdzieli wersjonowane moduły, np. system projektowy, klient API albo konfigurację lintera. Takie moduły twórz jako pakiety w obszarze roboczym (workspace) z jawnym package.json i polem exports, zamiast mapować sąsiednie katalogi przez tsconfig.paths. Jeśli lokalny pakiet wymaga transpilacji przez Next.js, dodaj go do transpilePackages.

Kiedy wprowadzić architekturę modułową w Next.js?

W małym projekcie zwykle wystarczy prosta struktura components/ + lib/. Jeśli od początku wiesz, z jakich obszarów biznesowych będzie się składać aplikacja (np. faktury, produkty, użytkownicy), a zespół jest większy, moduły mogą mieć sens od startu. Gdy poczujesz, że:

  • Szukasz plików dłużej niż 10 sekund
  • Nie wiesz, gdzie dodać nowy komponent
  • Zmiany w jednym module „łamią” coś w innym
  • Nowy członek zespołu nie może się odnaleźć w kodzie

...wtedy refaktoryzuj do modułów. Migracja jest przyrostowa — przenoś domenę po domenie, a nie wszystko naraz.

Elastyczne i wydajne narzędzia dla biznesu, które dotrzymają kroku Twojemu rozwojowi.
Next.js

Często zadawane pytania

Czy architektura modułowa działa z Pages Router?

Tak. Ta architektura dotyczy organizacji logiki, a nie konkretnego API routingu. W Pages Router katalog pages/ może być cienką warstwą importującą moduły z features/, choć nie ma tych samych konwencji i możliwości kolokacji co app/. Sama zasada grupowania kodu według domen biznesowych jest niezależna od tego, którego routera używasz.

Co, jeśli komponent jest używany w dwóch modułach?

Przenieś go do shared/components/, ale najpierw upewnij się, że jest naprawdę generyczny. Jeśli zawiera logikę specyficzną dla jednej domeny, lepsza bywa kontrolowana duplikacja niż tworzenie sztucznej, dziurawej abstrakcji, którą trzeba potem naginać do dwóch różnych przypadków. Współdzielenie ma sens dla rzeczy bez kontekstu domenowego — przycisku, okna modalnego, funkcji formatującej datę.

Jak architektura modułowa ma się do Domain-Driven Design?

To nie jest uproszczony DDD, lecz sposób fizycznej organizacji kodu, który może wspierać model domenowy. Moduł bywa mniejszy niż kontekst ograniczony (bounded context), a jeden kontekst może zawierać wiele modułów. DDD dotyczy przede wszystkim granic modelu, języka domenowego i zależności, nie nazw katalogów; agregaty ani event sourcing nie są obowiązkowe, aby stosować DDD.

Kiedy wprowadzić architekturę modułową w projekcie?

Nie zawsze od pierwszego dnia. W małym projekcie prosta struktura components/ plus lib/ jest w zupełności wystarczająca i wprowadzanie modułów byłoby przedwczesną komplikacją. Jeśli jednak od początku wiesz, z jakich obszarów biznesowych będzie się składać aplikacja (np. faktury, produkty, użytkownicy), a zespół jest większy, podział na moduły może mieć sens już na starcie. Sygnałem do refaktoru jest moment, gdy szukasz plików dłużej niż kilkanaście sekund, nie wiesz, gdzie dodać nowy kod, a zmiany w jednym module psują inny. Wtedy migruj — przyrostowo, domena po domenie.

Dlaczego moduły nie powinny importować z innych modułów?

Nie chodzi o bezwzględny zakaz, lecz o uniknięcie cykli i niejawnego sięgania do wnętrza innych modułów. Proste zależności realizuj przez publiczne API, a scenariusze łączące kilka domen składaj w warstwie aplikacyjnej. Elementy przekrojowe, takie jak sesja czy klient bazy, umieść w niższej warstwie shared/ albo core/, zamiast ogłaszać jeden moduł wyjątkiem od wszystkich reguł.

O autorze

Maciej Sala

Maciej Sala — konsultant technologiczny produktów cyfrowych i web developer z bogatym doświadczeniem w marketingu internetowym oraz SEO. Na co dzień pracuje z Reactem, Next.js i TypeScriptem, a ostatnio także z Astro i narzędziami do automatyzacji procesów AI. Sprawnie łączy perspektywę produktową z praktycznym podejściem do kodu. Przez kilka lat był związany z branżą gier wideo jako project manager i game designer. Absolwent historii na Uniwersytecie Jagiellońskim oraz studiów podyplomowych z marketingu internetowego na AGH w Krakowie. Po godzinach trenuje na siłowni, maluje figurki i rozwija własne projekty.

Pomagam przekładać takie tematy na konkretne wdrożenia w frontendzie, SEO, analityce i procesie produktowym.

Skontaktuj się ze mną
LH.pl – Hosting Mango

Biblioteka wiedzy na temat Next.js i React

Czytaj dalej

Zobacz więcej wpisów
Jak analizować i zmniejszyć paczkę JS w Next.js?

JavaScript to najbardziej kosztowny zasób wysyłany do przeglądarki. Każdy jego kilobajt musi zostać pobrany przez sieć, sparsowany i wykonany przez procesor, a następnie utrzymany w pamięci RAM. Na budżetowym smartfonie z wolniejszym łączem kilkaset kilobajtów kodu potrafi zablokować główny wątek i opóźnić pierwszą interakcję o kilka sekund. W tym artykule pokażę, jak namierzyć zbędny narzut w paczkach JS, odchudzić wysyłany kod i poprawić interaktywność aplikacji.

Maciej Sala

Maciej Sala

Founder StriveLab

Server i Client Components w Next.js: gdzie przebiega granica serwer–klient

Komponent działa lokalnie, ale po wdrożeniu na produkcję pojawia się niezgodność hydratacji ang. hydration mismatch , a prosta strona produktu pobiera kilkaset kilobajtów JavaScriptu. Zamiast natychmiast wyłączać SSR czy otaczać kod memoizacją, warto cofnąć się o krok. Problem rzadko leży w braku optymalizacji — częściej w braku decyzji, która część interfejsu realnie wymaga przeglądarki. React Server Components przesunęły granicę między serwerem a klientem. W App Routerze najpierw decydujemy, gdzie wykonać pracę, a dopiero potem dobieramy hooki i biblioteki.

Maciej Sala

Maciej Sala

Founder StriveLab

Next.js jako backend: architektura aplikacji full-stack

Next.js może obsługiwać interfejs, logikę biznesową i dostęp do bazy w jednym projekcie. Ten przewodnik pokazuje, jak połączyć komponenty serwerowe, Server Actions i Route Handlers z autoryzacją, cache i zadaniami w tle. Na przykładzie panelu zamówień przejdziemy od odczytu danych do zapisu i utrzymania na produkcji, wskazując momenty, w których warto wydzielić osobną usługę.

Maciej Sala

Maciej Sala

Founder StriveLab

LH.pl – Cloud Server 1C4G