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, ashared/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, gdzieButton.tsxleży obokInvoiceCalculator.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:
Masz:
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
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/.
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:
Reguła importowania:
'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:
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
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:
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.


