Publikowanie w npm i wersjonowanie semantyczne

Przed opublikowaniem zawsze należy uruchomić npm publish --dry-run. Polecenie to symuluje publikację bez faktycznego przesyłania czegokolwiek i pokazuje dokładnie, które pliki zostaną uwzględnione, jakie mają rozmiary oraz co zawiera archiwum tar pakietu. Pozwala wykryć typowe błędy, takie jak przypadkowe dołączenie plików źródłowych lub brak katalogu dist.

To, co zostanie opublikowane, można kontrolować za pomocą pola files w package.json: "files": ["dist", "README.md"]. Podejście oparte na białej liście jest bezpieczniejsze niż .npmignore, który działa jak czarna lista i może doprowadzić do ujawnienia poufnych plików, jeśli zapomni się je dodać. Zawsze należy uwzględnić dist, deklaracje typów i dokumentację. Nigdy nie należy dołączać src, testów ani node_modules.

Pakiety npm korzystają z wersjonowania semantycznego (semver): MAJOR.MINOR.PATCH. Numer MAJOR należy zwiększyć w przypadku zmian powodujących niezgodność wsteczną, takich jak usunięcie właściwości lub zmiana sygnatur API. Numer MINOR należy zwiększyć w przypadku nowych funkcji zgodnych wstecz, takich jak nowe komponenty lub nowe opcjonalne właściwości. Numer PATCH należy zwiększyć w przypadku poprawek błędów zgodnych wstecz. Wersja 0.x.x jest uznawana za przedstabilną, dlatego w jej przypadku wszystko może ulec zmianie.

Identyfikatory wersji przedpremierowej sygnalizują, że wersja nie jest gotowa do użycia w środowisku produkcyjnym: 1.0.0-alpha.1 oznacza wczesne kompilacje eksperymentalne, 1.0.0-beta.2 wersje kompletne pod względem funkcji, ale potencjalnie zawierające błędy, a 1.0.0-rc.1 (kandydat do wydania) wersje gotowe do końcowych testów. Wersje przedpremierowe należy publikować za pomocą npm publish --tag beta, aby nie stały się domyślnie instalowaną wersją.

Changesets to standardowe narzędzie do zarządzania wersjonowaniem pakietów i dziennikami zmian w bibliotekach komponentów. Przebieg pracy wygląda następująco: współtwórcy uruchamiają yarn changeset add, aby zarejestrować zakres zmian i ich typ (major/minor/patch). CI uruchamia yarn changeset version, aby zwiększyć wersje pakietów. Publikowanie odbywa się za pomocą yarn changeset publish, które przesyła pakiety do npm.

Changesets automatycznie generuje i aktualizuje CHANGELOG.md na podstawie plików changeset zatwierdzonych przez współtwórców. Każdy wpis zawiera numer wersji, datę wydania i opis zmian. Dzięki temu powstaje czytelna dla człowieka historia każdej wersji bez konieczności ręcznego prowadzenia dziennika zmian.

semantic-release to w pełni zautomatyzowane narzędzie do wersjonowania, które określa kolejną wersję na podstawie komunikatów konwencjonalnych commitów (feat: → minor, fix: → patch, BREAKING CHANGE: → major). Zwiększa numer wersji, generuje dziennik zmian i publikuje pakiet w npm — wszystkie te czynności są uruchamiane przez CI po scaleniu zmian z gałęzią main. Nie jest wymagane żadne ręczne zarządzanie wersjami.

Pakiety bez zakresu (my-component) są zawsze publiczne. Pakiety z zakresem (@myorg/my-component) są domyślnie ograniczone (prywatne) — aby opublikować je publicznie, należy użyć npm publish --access public. Pakiety o ograniczonym dostępie wymagają płatnego konta npm lub organizacji. Przed pierwszym opublikowaniem należy potwierdzić ustawienia dostępu.

Provenance npm łączy opublikowany pakiet z konkretnym commitem git w sposób możliwy do zweryfikowania. Należy włączyć tę funkcję za pomocą npm publish --provenance w GitHub Actions. Użytkownicy mogą sprawdzić, czy zainstalowany przez nich pakiet został zbudowany dokładnie z tego commitu źródłowego, który jest wskazany na stronie pakietu w rejestrze npm. Znacząco zwiększa to bezpieczeństwo łańcucha dostaw.

Gdy wersja zawiera krytyczny błąd lub zmianę powodującą niezgodność wsteczną, należy ją wycofać: npm deprecate your-package@1.2.3 "Security vulnerability, upgrade to 1.2.4". npm wyświetli ostrzeżenie o wycofaniu każdej osobie instalującej tę wersję. Nie usuwa to wersji — npm domyślnie nie usuwa opublikowanych wersji — lecz informuje użytkowników, że należy ją zaktualizować.

Pakiety z zakresem korzystają z formatu @scope/package-name. Zakres zazwyczaj odpowiada nazwie użytkownika npm lub nazwie organizacji. Pakiety z zakresem jasno wskazują, kto je utrzymuje, i zapobiegają konfliktom nazw z pakietami bez zakresu. Należy używać pakietów z zakresem w przypadku pakietów prywatnych oraz pakietów open source powiązanych z organizacją.

Zgodnie z wersjonowaniem semantycznym, kiedy należy zwiększyć numer wersji MAJOR?

Za pomocą npm publish --dry-run można wyświetlić podgląd publikacji, a pole files pozwala kontrolować to, co zostanie opublikowane. Wersjonowanie semantyczne: MAJOR oznacza zmiany powodujące niezgodność wsteczną, MINOR nowe funkcje, a PATCH poprawki. Wersje przedpremierowe korzystają z tagów -alpha/-beta/-rc. Changesets automatyzuje wersjonowanie i generowanie CHANGELOG w przypadku bibliotek tworzonych zespołowo. semantic-release automatyzuje ten proces na podstawie commitów konwencjonalnych. Włączenie --provenance zwiększa bezpieczeństwo łańcucha dostaw. Błędne wersje można wycofywać za pomocą npm deprecate.