Przy starcie projektu Node.js najważniejsze nie jest samo napisanie pierwszego pliku, tylko ustawienie fundamentów: poprawnego manifestu, sensownego trybu modułów i prostych skryptów uruchomieniowych. Do szybkiego startu przydaje się npm init, bo porządkuje ten etap bez ręcznego klejenia plików. Poniżej wyjaśniam, co dokładnie tworzy, kiedy wybrać wersję automatyczną, jak dobrać kluczowe pola i jakie błędy najczęściej spowalniają początkujących.
Najważniejsze rzeczy, które warto zapamiętać
- To polecenie tworzy bazę projektu w postaci `package.json`, a nie gotowy szkielet aplikacji.
- Wersja automatyczna z `-y` jest dobra do szybkich testów, ale przy realnym projekcie lepiej świadomie ustawić nazwę, licencję i typ modułów.
- Najważniejsze pola na start to `name`, `version`, `scripts`, `type` i `private`.
- Jeśli planujesz `import` i `export`, ustaw odpowiedni typ modułów od razu, zanim projekt urośnie.
- Najczęstszy błąd to mylenie inicjalizacji projektu z instalacją zależności albo generowaniem frameworkowego boilerplate’u.
Co naprawdę robi to polecenie i kiedy po nie sięgam
Ja traktuję ten etap nie jako tworzenie całego projektu, tylko jako przygotowanie jego metadanych. Inicjalizacja tworzy przede wszystkim plik `package.json`, czyli centralny opis aplikacji albo biblioteki: nazwę, wersję, skrypty, typ modułów i kilka dodatkowych ustawień.
To ważne rozróżnienie: samo polecenie nie instaluje jeszcze bibliotek i nie generuje gotowego boilerplate’u aplikacji. Nie dostajesz po nim automatycznie Reacta, Vite ani Expressa. Dostajesz natomiast punkt startowy, od którego npm zaczyna rozumieć, czym jest twój projekt.
- używam tego od razu, gdy tworzę nowy projekt JavaScript w Node.js;
- uruchamiam to też wtedy, gdy chcę dodać porządek do istniejącego katalogu z kodem;
- nie mylę tego z instalacją zależności, bo to dopiero kolejny krok;
- traktuję `package.json` jako źródło prawdy dla skryptów i ustawień projektu.
Gdy rozumiesz tę różnicę, łatwiej dobrać odpowiedni tryb startu. I właśnie to jest dobry moment, żeby zobaczyć, jak przejść przez inicjalizację bez zgadywania.
Jak przejść przez inicjalizację bez zgadywania
Masz dwa praktyczne podejścia: przejść przez pytania krok po kroku albo skorzystać z wartości domyślnych. Ja wybieram wersję automatyczną tylko wtedy, gdy robię szybki prototyp, testuję pomysł albo wiem, że i tak zaraz dopracuję manifest ręcznie.
npm init -yW tym wariancie narzędzie wypełnia plik sensownymi domyślnymi wartościami. Zwykle dostajesz nazwę opartą o nazwę katalogu, wersję `1.0.0`, pusty opis, domyślny skrypt testowy i licencję `ISC`. To wygodne, ale nie jest jeszcze decyzją projektową. To tylko skrót, który oszczędza kilka minut.
Jeśli tworzysz bibliotekę, aplikację zespołową albo projekt, który ma żyć dłużej niż kilka godzin, lepiej przejść przez pytania świadomie. Szczególnie wtedy, gdy od początku wiesz, że potrzebujesz innego typu modułów, innej licencji lub informacji, które później będą widoczne dla innych osób.
W praktyce szybka wersja jest dobra do prototypu, a interaktywna do czegoś, co ma stać się realnym projektem. Z tego od razu wynika następny temat: jakie pola w `package.json` naprawdę warto ustawić od razu, zamiast zostawiać je przypadkowi.
Jakie pola w package.json ustawiam od razu
Najwięcej różnicy robi nie sama inicjalizacja, tylko to, co zrobisz z plikiem po niej. Ja zwykle od razu sprawdzam kilka pól, bo to one decydują, czy projekt będzie wygodny w pracy zespołowej i czy później nie będę poprawiał podstawowych ustawień po omacku.
| Pole | Co ustawiam na starcie | Po co to robię |
|---|---|---|
name |
Krótką, czytelną nazwę projektu | Identyfikuje paczkę i porządkuje publikację oraz instalację |
version |
Zwykle 1.0.0
|
Daje sensowny punkt startowy dla wersjonowania |
type |
module albo brak pola, jeśli zostaję przy CommonJS |
Decyduje o tym, jak Node interpretuje pliki `.js` |
scripts |
dev, start i test
|
Ułatwia uruchamianie projektu bez pamiętania długich komend |
private |
true dla aplikacji |
Chroni przed przypadkową publikacją prywatnego projektu |
license |
MIT, ISC albo inna licencja zgodna z celem projektu | Jasno określa zasady użycia kodu przez innych |
Jeśli projekt ma być biblioteką, później dorzucam też `main` albo `exports`. Jeśli to aplikacja, ważniejsze stają się `start`, `dev` i `test` niż pola publikacyjne. To właśnie te decyzje odróżniają pusty manifest od sensownie przygotowanego projektu.
Najbardziej niedoceniane pole to zwykle `type`. Gdy wiem, że kod ma działać z `import` i `export`, ustawiam je od razu. Jeśli tego nie zrobię, późniejsze przechodzenie między CommonJS a ESM potrafi wprowadzić niepotrzebny chaos, zwłaszcza gdy projekt zaczyna rosnąć.
Skoro manifest ma już sensowną bazę, warto jeszcze odróżnić zwykły start od sytuacji, w której potrzebujesz gotowego szablonu. To nie to samo i w praktyce prowadzi do różnych decyzji.
Kiedy zwykły start projektu to za mało
Sam manifest wystarcza do prostego projektu, ale nie zawsze do wygodnego startu. Jeśli budujesz aplikację na frameworku, generator szkieletu zwykle zrobi więcej: utworzy katalogi, doda gotowe pliki i ustawi konwencje. To inna warstwa niż sama inicjalizacja.
Ja rozdzielam te dwa scenariusze bardzo wyraźnie:
- czysty Node.js - gdy chcesz sam zbudować strukturę i kontrolować każdy plik;
- starter frameworka - gdy zależy ci na gotowym układzie folderów, konfiguracji bundlera i domyślnych zależnościach;
- mała biblioteka - gdy liczy się lekki manifest, przejrzysty `main` lub `exports` i brak zbędnego narzutu;
- monorepo - gdy planujesz kilka pakietów w jednym repozytorium i potrzebujesz kolejnych workspace’ów.
Mechanizm gotowych inicjalizatorów bywa wygodny, ale ma też ograniczenie: daje tyle, ile przewidział autor szablonu. Jeśli chcesz nietypowej struktury albo bardzo lekkiego setupu, prosty start bywa lepszy niż „magiczny” generator. A to prowadzi wprost do błędów, których najłatwiej uniknąć na samym początku.
Najczęstsze błędy, które psują dobry początek
Na początku najwięcej strat robi nie brak wiedzy, tylko pośpiech. Widziałem już projekty, które były poprawne technicznie, ale od pierwszego dnia miały zły katalog, nieczytelny manifest albo ustawienia niepasujące do sposobu pracy zespołu.
- Uruchamianie w złym folderze - potem plik trafia nie tam, gdzie trzeba, a struktura robi się chaotyczna.
- Zostawienie domyślnego skryptu testowego - to dobry placeholder, ale nie powinien zostać na długo w prawdziwym projekcie.
- Spóźnione ustawienie typu modułów - jeśli planujesz `import` i `export`, lepiej zdecydować o tym przed rozbudową kodu.
- Traktowanie manifestu jak śmieciowego pliku - a to on steruje skryptami, metadanymi i zależnościami.
- Ręczne dopisywanie byle czego - `package.json` musi pozostać poprawnym JSON-em, bez komentarzy i przypadkowych przecinków.
- Zakładanie, że wszystko da się naprawić później - da się, ale przy większym projekcie koszt jest większy niż pięć minut namysłu na starcie.
Jeśli unikniesz tych rzeczy, start będzie prostszy niż większość początkujących zakłada. I wtedy można już spokojnie przejść do końcowego wyboru: co zrobić zaraz po inicjalizacji, żeby projekt faktycznie był gotowy do pracy.
Jak zamienić inicjalizację w solidny fundament aplikacji
Ja zwykle po inicjalizacji robię trzy rzeczy od razu: ustawiam typ modułów, dopisuję pierwsze skrypty i sprawdzam, czy manifest opisuje projekt tak, jak naprawdę ma działać. To wystarcza, żeby mały katalog z kodem zamienić w uporządkowany start pod aplikację albo bibliotekę.
- dla aplikacji webowej najczęściej ustawiam `private: true`, żeby nie publikować jej przypadkiem jako paczki;
- dla biblioteki pilnuję nazwy, wersji i tego, jak będzie eksportowany kod;
- dla pracy zespołowej od początku dopisuję `dev`, `start` i `test`, zamiast zostawiać wszystko w ręcznym odpalaniu plików;
- dla większych repo planuję strukturę wcześniej, zanim dojdą kolejne pakiety i zależności.
Najlepszy efekt daje tu prostota: jedno uporządkowane wejście, jasny `package.json` i decyzje techniczne podjęte zanim projekt się rozrośnie. Wtedy inicjalizacja nie jest formalnością, tylko realnym fundamentem dalszej pracy.
