Kategoria: Next.js, React i TypeScript

TypeScript TS2688 Cannot find type definition file dla Node

Poradnik techniczny · Kacper Bernecki

Kompilator zgłasza brak deklaracji Node, choć kod JavaScript buduje się przez bundler. tsconfig może wymagać types: ["node"] bez zainstalowanego pasującego @types/node w danym workspace.

Jak rozpoznać źródło problemu

Otwórz pełny komunikat i sprawdź listę types w tsconfig oraz obecność @types/node w lockfile. Porównaj wersję runtime i pakietu deklaracji oraz katalog, w którym uruchamiasz npm ci.

Porównaj komunikat z konsoli z wynikiem kompilacji produkcyjnej oraz stanem po odświeżeniu strony.

Kroki naprawcze

Dodaj odpowiednie @types/node jako zależność developerską do właściwego pakietu, jeśli projekt faktycznie używa API Node. Jeśli pliki są tylko frontendowe, skonfiguruj oddzielny tsconfig zamiast narzucać im globalne typy serwerowe.

Jak przetestować rozwiązanie

Czysta instalacja i tsc przechodzą, a deklaracje DOM i Node nie mieszają przypadkowo zewnętrznych obiektów.

Bezpieczeństwo i ograniczenia

Nie kopiuj zawartości node_modules z innego komputera zamiast poprawić manifest paczek.