Frontend Academy · Lekcja

Wersjonowanie i publikowanie w npm

Zastosuje Pan/Pani semantyczne wersjonowanie, zautomatyzuje generowanie dziennika zmian za pomocą Changesets lub standard-version i opublikuje bibliotekę w npm albo prywatnym rejestrze.

Wersjonowanie i publikowanie w npm to bezpłatna lekcja Frontend Academy na CoddyKit. To lekcja 3 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej Frontend Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs Frontend Academy zawiera 4 lekcji w sumie.

Dlaczego publikować w npm?

Jeśli z systemu projektowego korzysta więcej niż jedna aplikacja, należy opublikować go jako pakiet. Odbiorcy instalują go za pomocą npm/yarn/pnpm, przypinają wersje i aktualizują pakiet zgodnie z własnym harmonogramem.

Wersjonowanie semantyczne (SemVer)

Wersje mają format MAJOR.MINOR.PATCH. MAJOR: zmiany niezgodne wstecz. MINOR: nowe funkcje zgodne wstecz. PATCH: wyłącznie poprawki błędów.

Kiedy zwiększać wersję

Zmiana nazwy propsa? MAJOR. Dodanie nowego opcjonalnego propsa? MINOR. Poprawka błędu CSS? PATCH. Wydania przed wersją 1.0 (0.x.y) mogą wprowadzać niezgodne zmiany w MINOR — ale warto zachować umiar.

package.json — manifest

Należy skonfigurować sposób prezentowania pakietu w npm.

{
  "name": "@yourorg/design-system",
  "version": "1.4.2",
  "main": "dist/index.cjs.js",
  "module": "dist/index.esm.js",
  "types": "dist/index.d.ts",
  "exports": {
    ".": { "import": "./dist/index.esm.js", "require": "./dist/index.cjs.js" },
    "./theme": "./dist/theme.js"
  },
  "files": ["dist", "README.md"],
  "peerDependencies": { "react": "^18.0.0" }
}

Wynik budowania

Należy dostarczać CommonJS, ESM i deklaracje typów. Narzędzia takie jak tsup lub vite build --lib obsługują to automatycznie.

// tsup.config.ts
export default {
  entry: ['src/index.ts'],
  format: ['cjs', 'esm'],
  dts: true,
  clean: true,
  external: ['react', 'react-dom']
};

// package.json: "build": "tsup"

peerDependencies

React/Vue itd. należy umieścić na liście peerDependencies, aby odbiorcy korzystali z własnej wersji. Oznaczenie ich jako zwykłych zależności spowoduje dwukrotne dołączenie ich do bundla — co prowadzi do problemów z hookami i kontekstem.

Przyjazność dla tree-shakingu

Należy używać eksportów ESM i unikać efektów ubocznych, aby bundlery mogły usunąć nieużywane komponenty. W package.json należy ustawić: "sideEffects": false (lub wymienić konkretne pliki, takie jak CSS).

Publikowanie w npm

Wystarczy raz się zalogować, a następnie opublikować pakiet.

npm login

# Bump version + publish:
npm version patch   # 1.4.2 -> 1.4.3
npm publish

# Or scoped public package:
npm publish --access public

Automatyzacja wydań za pomocą Changesets

Changesets to nowoczesny zestaw narzędzi do publikowania monorepo i bibliotek. Pull requesty zawierają plik „changeset” opisujący zmianę; CI wydania zwiększa numery wersji i publikuje pakiety.

npm install -D @changesets/cli
npx changeset init

# In each PR:
npx changeset
# pick package, type (major/minor/patch), describe change
# commits .changeset/<random>.md

# CI on main:
npx changeset version  # bumps versions in package.json + generates changelog
npx changeset publish  # publishes to npm

Automatyczny changelog

Changesets automatycznie generuje plik CHANGELOG.md dla każdego pakietu na podstawie opisów w changesetach — odbiorcy mogą sprawdzić, co zmieniło się w każdej wersji.

Tagi dystrybucji npm

Do wydań przedpremierowych należy używać tagów dystrybucji: npm publish --tag beta publikuje pakiet bez nadpisywania wersji latest. Odbiorcy wyrażają zgodę na użycie wersji beta za pomocą npm install @yourorg/design-system@beta.

Prywatne rejestry

Pakiety wewnętrzne mogą korzystać z GitHub Packages, GitLab Package Registry lub hostowanego samodzielnie Verdaccio. Konfigurację należy umieścić w .npmrc: @yourorg:registry=https://npm.pkg.github.com.

Wycofywanie starych wersji

Wersję można oznaczyć jako przestarzałą, aby ostrzegać osoby instalujące pakiet.

npm deprecate @yourorg/design-system@1.0.0 'Use 2.x for React 18 support'

Szybkie sprawdzenie

Jeśli zmienią Państwo nazwę propsa w eksportowanym komponencie, jaki rodzaj zwiększenia wersji SemVer jest wymagany?

Podsumowanie: wersjonowanie i publikowanie

SemVer: MAJOR.MINOR.PATCH — odpowiednio zmiana niezgodna, funkcja i poprawka. Należy budować CJS + ESM + typy (tsup, vite --lib). React/Vue należy deklarować jako peerDependencies. sideEffects:false umożliwia tree-shaking. Publikowanie w npm odbywa się za pomocą npm publish lub automatycznie przez Changesets. CHANGELOG jest generowany automatycznie. Tagi dystrybucji służą do wydań beta. Prywatne rejestry są przeznaczone dla pakietów wewnętrznych.

Często zadawane pytania

Czy lekcja „Wersjonowanie i publikowanie w npm” jest bezpłatna?

Tak — pełny tekst „Wersjonowanie i publikowanie w npm” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu Frontend Academy, przejdź na CoddyKit PRO. Kurs Frontend Academy zawiera 4 lekcji w sumie.

Co nauczysz się w „Wersjonowanie i publikowanie w npm”?

Zastosuje Pan/Pani semantyczne wersjonowanie, zautomatyzuje generowanie dziennika zmian za pomocą Changesets lub standard-version i opublikuje bibliotekę w npm albo prywatnym rejestrze. Ćwiczysz Frontend Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć Frontend Academy?

Nie wymagamy żadnego doświadczenia. Frontend Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 3 z 4.

Ile czasu zajmuje lekcja „Wersjonowanie i publikowanie w npm”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji Frontend Academy?

Tak. Każda lekcja Frontend Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

← Powrót do Frontend Academy