Next.js: diagnostyka błędnych importów między Client i Server Components
Poradnik techniczny · Kacper Bernecki
W Next.js od rozdzielenia komponentów na server i client (RSC/CSR) błędne lub mieszane importy są częstą przyczyną błędów podczas budowania aplikacji i przy uruchomieniu w środowisku produkcyjnym. Ten dokument opisuje różnicową diagnostykę, konkretne testy i sekwencję kroków pozwalających znaleźć i naprawić sytuacje, gdy komponent oznaczony jako server importuje moduł używający stanu lub efektów przeglądarki, albo gdy client component zależy od kodu wymagającego node-only API. Skupiam się na rzeczywistych warunkach, które powodują: błędy kompilacji typu "use client must be the first directive", błędy czasu wykonywania przy hydracji, czy nieoczekiwanym zachowaniu w produkcji (np. różne dane renderowane w dev i prod). Nie zakładam, że przyczyną jest pojedynczy plik — pokażę typowe warianty źródłowe, konkretne komendy i warunki testowe. Proponowane kroki są wykonywalne w repozytorium Next.js (wersje 13+ z RSC) i nie wymagają narzędzi zewnętrznych poza node, npm/yarn oraz poleceniami Next.js. Nie tworzę fikcyjnych patchy ani nie obiecuję rozwiązania w jednym kroku — wskazuję powtarzalne testy i warunki, które jednoznacznie identyfikują źródło konfliktu importów oraz ich naprawy.
Jak rozpoznać przyczynę
Objawy 1: błąd kompilacji podczas build lub w konsoli dev: "'use client' must be the first directive" albo stacktrace wskazujący na import cyclical. Taki komunikat pojawia się, gdy plik klienta nie ma 'use client' na pierwszej linii lub importowana zależność jest server-only. Sprawdź pierwsze 3 wiersze każdego komponentu, by potwierdzić brak dodatkowych komentarzy przed 'use client'.
Objawy 2: runtime hydration mismatch, brak efektów useEffect lub błędy typu window is not defined w produkcji. To sugeruje, że server component importuje moduł próbujący użyć API przeglądarki. Sprawdź importy pochodzące z bibliotek korzystających z DOM (np. bibliotek UI/ikonek) i przeprowadź analizę zależności tree-shaking/webpack.
Objawy 3: różne zachowanie dev vs production: działa lokalnie, ale build na Vercel/CI zwraca błąd. Często wynika to z różnic wersji Node, różnych flag kompilatora lub z tego, że w dev serwer jest bardziej tolerancyjny. Upewnij się co do wersji Node i przebiegu polecenia next build z --profile lub --debug.
Rozwiązanie krok po kroku
1. Krok 1 — lokalizowanie: uruchom next build i skopiuj pełny stacktrace. Jeśli pojawia się komunikat o 'use client' lub "window is not defined", zanotuj plik wskazywany w ścieżce. Użyj grep (np. rg "use client") na katalogu /app i /components by znaleźć wszystkie client components.
2. Krok 2 — weryfikacja bezpośrednich importów: dla wskazanego pliku otwórz każdy import i sprawdź, czy importowana ścieżka zawiera 'use client' lub używa React hooks/efektów. Jeśli import jest bezpośrednio do biblioteki, sprawdź jej dokumentację czy obsługuje server rendering.
3. Krok 3 — analiza dependency tree: uruchom npm ls <pakiet> lub narzędzie do wyświetlania grafu pakietów (np. npm-why) aby znaleźć pośrednie zależności, które mogą wprowadzać kod przeglądarkowy do server component. Zidentyfikuj moduły, które eksportują DOM-dependent code.
4. Krok 4 — izolacja: tymczasowo zastąp podejrzany import stubem (prosty komponent bez efektów) i powtórz next build. Jeśli build przejdzie, wiesz, że problem pochodzi z tej zależności. Przywróć oryginał i kontynuuj izolację na dalszym poziomie zależności.
5. Krok 5 — naprawa: jeśli to server component importuje client-only kod, przenieś import do client component lub opakuj moduł dynamicznym importem z { ssr: false } dla części wymagającej przeglądarki. Alternatywnie oznacz plik klienta 'use client' i upewnij się, że jest używany jedynie w miejscu, które akceptuje client components.
6. Krok 6 — sprawdzenie konfiguracji: porównaj wersję Node i ustawienia next.config.js (experimental appDir, transpilePackages itp.) między lokalnym środowiskiem a CI. Wprowadź zmiany w celu ujednolicenia środowiska i powtórz next build.
Jak sprawdzić, czy problem zniknął
Test 1 — budowanie: uruchom clean build (rm -rf .next && npm run build) i sprawdź brak błędów kompilacji. Powodem jest potwierdzenie, że żaden server component nie importuje client-only zależności. Zwróć uwagę na czas kompilacji i brak nowych warningów.
Test 2 — uruchomienie produkcyjne lokalnie: uruchom NODE_ENV=production npm start i odwiedź ścieżkę, która wcześniej powodowała błąd. Sprawdź konsolę przeglądarki pod kątem hydration mismatch i brak błędów typu window is not defined.
Test 3 — kontrola zależności: uruchom npm ls <podejrzany-pakiet> i potwierdź, że nie występuje w ścieżkach importu server component. Jeśli występuje, powtórz izolację i naprawę dla pośrednich modułów.
Czego nie robić
Nie oznaczaj pliku 'use client' jako rozwiązania domyślnego bez sprawdzenia wpływu: nadmiar client components powoduje utratę korzyści RSC i może ukryć rzeczywistą zależność serwerową.
Nie polegaj tylko na dev serverze: dev może maskować błędy dzięki odświeżaniu i tolerancji importów; zawsze testuj clean build i uruchomienie w trybie production.
Unikaj wprowadzania globalnych polyfilli dla window/DOM w serverze; to ukrywa problem i może prowadzić do niestabilnego zachowania w środowisku produkcyjnym.