Generator .npmrc

Generator pliku .npmrc

Plik .npmrc w katalogu projektu ustawia zachowanie npm dla wszystkich osób pracujących z repozytorium — bez konieczności ręcznej konfiguracji.

Najważniejsze opcje

Przykład

Ustawienie save-exact=true sprawia, że npm install lodash zapisze dokładną wersję zamiast zakresu. Dzięki temu różne środowiska instalują identyczne wersje pakietów.

Prywatne rejestru

Dla prywatnego rejestru (np. Nexus, Artifactory) ustaw registry na jego adres. Token autoryzacyjny dodawaj przez //registry/:_authToken=..., ale trzymaj go poza repozytorium.

Jak działa generator .npmrc i skąd npm bierze konfigurację

Plik .npmrc to zwykły plik tekstowy, w którym każda linia ma postać klucz=wartość. npm odczytuje go przy każdym wywołaniu komendy — nie tylko podczas instalacji. Generator tworzy taki plik na podstawie wybranych opcji, ale nie modyfikuje istniejącej konfiguracji w systemie. Oznacza to, że nowe ustawienia zaczną obowiązywać natychmiast po zapisaniu pliku w katalogu projektu, bez potrzeby ponownego uruchamiania terminala.

npm przeszukuje kilka lokalizacji w określonej kolejności: najpierw flagi wiersza poleceń, potem zmienne środowiskowe, następnie projektowy .npmrc, dalej .npmrc użytkownika w katalogu domowym, a na końcu globalny plik konfiguracyjny npm. W przypadku konfliktu wygrywa źródło o wyższym priorytecie. Generator przygotowuje zawartość dla pliku projektowego, który nadpisuje ustawienia użytkownika i globalne, ale ustępuje miejscom flagom i zmiennym środowiskowym.

Warto pamiętać, że część opcji działa tylko w momencie instalacji nowych pakietów, a inne wpływają na każdą operację. Na przykład save-exact zmienia sposób zapisu wersji w package.json, a registry przekierowuje cały ruch do wskazanego serwera. Narzędzie nie waliduje poprawności wartości — jeśli wpiszesz błędny adres rejestru, npm zgłosi błąd dopiero przy próbie pobrania pakietu.

Przykład krok po kroku: wymuszenie dokładnych wersji

1. Zakładasz nowy projekt i chcesz, aby wersje pakietów były zapisywane bez zakresów. Tworzysz plik package.json poleceniem npm init -y.
2. Bez pliku .npmrc uruchamiasz npm install [email protected]. W package.json pojawia się zapis "example-package": "^1.0.0".
3. Generujesz plik .npmrc za pomocą tego narzędzia, zaznaczając opcję save-exact=true.
4. Usuwasz katalog node_modules i wpis z package.json, a następnie ponownie uruchamiasz npm install [email protected].
5. Tym razem w package.json zapisuje się "example-package": "1.0.0" — bez znaku ^. Gdy w rejestrze pojawi się wersja 1.0.1, kolejne npm install nie zaktualizuje pakietu, ponieważ wymagana jest dokładnie wersja 1.0.0. Wynik: instalacja zawsze odtwarza identyczny zestaw wersji, co eliminuje różnice między środowiskami.

Priorytet źródeł konfiguracji npm

Praktyczne wskazówki przy konfiguracji .npmrc

• Trzymaj projektowy .npmrc w repozytorium — dzięki temu cały zespół używa tych samych ustawień rejestru i formatu zapisu wersji. Pamiętaj jednak, aby nie umieszczać w nim tokenów ani innych sekretów.
• Używaj zmiennych środowiskowych dla poufnych danych — zamiast wpisywać token na sztywno, odwołaj się do ${NPM_TOKEN}, który ustawiasz w systemie CI lub lokalnie w powłoce. Plik .npmrc może wtedy bezpiecznie trafić do repozytorium.
• Sprawdzaj aktywną konfigurację poleceniem npm config list — pokazuje ono wszystkie aktywne ustawienia oraz źródło ich pochodzenia. To najszybszy sposób, aby upewnić się, że projektowy plik jest rzeczywiście czytany.
• Dla pakietów scoped ustaw osobny rejestr — wpis @twoja-firma:registry=https://... przekierowuje tylko pakiety z danym zakresem, nie zmieniając globalnego registry dla całego projektu. To przydatne, gdy część zależności pochodzi z publicznego npm, a część z wewnętrznego serwera.
• Testuj zmiany na kopii projektu — błędny wpis w .npmrc może uniemożliwić instalację wszystkich pakietów. Zanim zatwierdzisz zmiany w repozytorium, sprawdź, czy npm install nadal działa poprawnie.

Czego narzędzie nie uwzględnia

• Brak walidacji adresu registry — generator nie sprawdza, czy podany URL jest poprawny, osiągalny ani czy wymaga uwierzytelnienia. Literówka w adresie ujawni się dopiero podczas instalacji pakietu.
• Nie scala z istniejącym .npmrc — narzędzie tworzy nowy plik od zera. Jeśli w projekcie lub katalogu domowym masz już własne ustawienia, musisz ręcznie połączyć je z wygenerowaną zawartością.
• Nie obsługuje zaawansowanego uwierzytelniania — tokeny OAuth, certyfikaty klienta czy konfiguracja proxy dla wielu rejestrów wymagają ręcznej edycji pliku. Generator ogranicza się do podstawowych opcji tekstowych.
• Nie uwzględnia innych menedżerów pakietów — yarn i pnpm mają własne pliki konfiguracyjne (np. .yarnrc.yml) i część opcji z .npmrc może nie być przez nie respektowana. Wynikowy plik jest przeznaczony wyłącznie dla npm.

Najczęstsze pytania