Npm a Yarn správa balíčků

Proč řešit správu balíčků v ekosystému Node.js

Správa balíčků je páteří vývoje v Node.js. Nástroje npm a Yarn řídí instalaci závislostí, verzování, skripty, workspace monorepa i publikaci modulů. Cílem je deterministická, bezpečná a rychlá reprodukovatelnost prostředí napříč týmy, CI/CD a produkcí. Tento článek srovnává klíčové koncepty, postupy a rozdíly mezi npm a Yarn (Classic i Berry) a představuje doporučené postupy.

Architektura: registry, klient, resolver a linker

• Registry: Výchozí je veřejný registr npm. Lze využít privátní registry a proxy (např. Verdaccio, Nexus, Artifactory) pro cache a řízení přístupu.
• Resolver: Řeší strom závislostí podle pravidel semver, peer závislostí a rozlišení přímých a transitivních závislostí.
• Linker: Vytváří fyzickou reprezentaci stromu (adresář node_modules, nebo u Yarn PnP virtuální mapování).

Základní workflow a inicializace projektu

• Inicializace: npm init -y nebo yarn init -2 (Yarn Berry) vytvoří package.json a případně .yarnrc.yml.
• Instalace závislostí: npm install resp. yarn install. Přidání balíčku: npm i react nebo yarn add react.
• Odstranění: npm uninstall vs. yarn remove; aktualizace: npm update vs. yarn up.

Soubor package.json: kontrakt projektu

package.json definuje metadata balíčku, skripty a závislosti. Klíčové sekce:

• name, version: Identita balíčku a semver verze.
• scripts: Příkazy spouštěné přes npm run nebo yarn (např. build, test, start).
• dependencies, devDependencies: Pro běhové vs. vývojové závislosti.
• peerDependencies, optionalDependencies: Pro pluginy a volitelné funkce s měkkými požadavky.
• engines: Požadované verze Node.js a npm/yarn pro konzistentní běh.
• exports, main, types: Vstupní body pro ESM/CJS a typové deklarace.

Semver a rozsahy verzí

• Major.Minor.Patch: 1.2.3; major může obsahovat breaking changes, minor přidává funkce, patch opravuje chyby.
• Rozsahy: ^1.2.3 povolí minor/patch, ~1.2.3 pouze patch; pevná verze pinning minimalizuje drift.
• Pre-release: 1.2.3-beta.1 vyžaduje explicitní povolení u resolveru.

Lockfile: deterministická reprodukovatelnost

• npm: package-lock.json uzamyká přesné verze a integritní hashe.
• Yarn: yarn.lock (Classic) nebo yarn.lock s metadaty Berry; verze lockfile se liší mezi generacemi.
• Praxe: Commitovat do VCS, neměnit ručně, invalidovat při změně registru. V CI používat npm ci nebo yarn install --immutable pro striktní konzistenci.

Node_modules vs. Plug’n’Play (Yarn Berry)

• node_modules model: Tradiční fyzický strom závislostí, kompatibilní se všemi nástroji; může být velký a duplicitní.
• Yarn PnP: Virtuální mapování bez node_modules; rychlejší instalace a rozlišení; vyžaduje kompatibilitu nástrojů a PnP loader.
• Volba linkeru: Yarn umí přepnout nodeLinker: node-modules pro kompatibilitu.

Workspaces a monorepo

• npm workspaces: Definice balíčků v monorepu, sdílený lockfile, lokální linking mezi balíčky.
• Yarn workspaces: Pokročilé funkce (constraints, protocache, yarn workspaces foreach), granulární skriptové běhy a paralelizace.
• Best practice: Jeden lockfile v kořeni, konzistentní omezení verzí a centralizované skripty.

Skripty a lifecycle

• Spouštění: npm run build nebo yarn build; implicitní mapování na node_modules/.bin.
• Lifecycle hooks: prebuild, postbuild, prepare (užitečné pro git-based instalace), prepublishOnly pro kontrolu před publikací.
• Orchestrace: Paralelní běhy přes npm run -ws nebo yarn workspaces foreach -p.

Peer dependencies a jejich rozlišení

• Smysl: Plugin očekává hostitelský balíček (např. React plugin vyžaduje React určité verze).
• npm: Moderní npm může peer závislosti automaticky instalovat pouze za určitých podmínek, pořád je ale zodpovědnost na hostiteli.
• Yarn: Berry nabízí pravidla rozlišení a resolutions nebo packageExtensions pro nápravu chyb v cizích balíčcích.

Resolutions, overrides a deduplikace

• npm overrides: Sekce overrides nutí konkrétní verze transitivních závislostí.
• Yarn resolutions: Pole resolutions (Classic) a pokročilejší constraints (Berry) s pravidly nad závislostmi.
• Deduplikace: npm dedupe nebo yarn dedupe pro kompaktnější strom a menší footprint.

Cache, výkon a determinismus v CI

• Cache adresářů: Cache ~/.npm, ~/.cache/yarn a případně .yarn/cache (Berry) mezi běhy CI.
• Immutabilní instalace: npm ci a yarn install --immutable --check-cache zajistí shodu s lockfile.
• Offline instalace: Yarn Berry umí plně offline z .yarn/cache s předem staženými artefakty.

Zabezpečení a audit

• Audit zranitelností: npm audit a npm audit fix; Yarn může volat audit npm registru příkazem yarn npm audit (Berry) nebo přes pluginy.
• Integrita: Hashy v lockfile brání podvržení artefaktů, doporučeno kontrolovat integritu v CI.
• Tokeny a 2FA: Publikace a přístup do soukromých registrů s access tokeny, doporučeno povolit dvoufaktor.

Publikace balíčků

• npm publish: Publikuje podle files, .npmignore a publishConfig. Štítky (dist-tags) jako latest, next umožní bezpečné rollouty.
• Yarn: V Classic využívá yarn publish (wrap npm); Berry poskytuje yarn npm publish a správu verzí přes yarn version.
• Monorepo: Verzování balíčků koordinujte nástroji typu Changesets, případně Yarn version plugins.

ESM vs. CJS a rozložení balíčků

• Dual publishing: Export polí exports s podmínkami pro ESM/CJS, pole type: module a kompatibilní main/module.
• Typy: types a bundling deklarací pro TypeScript, respektive generování pomocí tsc nebo bundlerů.

Migrace mezi npm a Yarn

• Lockfile: Při přechodu generujte nový lockfile daného nástroje, nemažte původní bez zálohy a otestujte reprodukovatelnost.
• PnP kompatibilita: Pokud nástroje nefungují s PnP, přepněte Yarn na node-modules.
• Workspaces: Ujistěte se, že skripty a build kroky respektují syntaxi konkrétního nástroje.

Konfigurace a správa registrů

• .npmrc a .yarnrc.yml: Nastavení registrů, tokenů, always-auth, politik cache a auditů.
• Scoped registry: Např. @company:registry=https://registry.example.com pro interní balíčky.

Diagnostika a řešení problémů

• Čistá instalace: Smazat node_modules a lockfile, pak npm ci nebo yarn install --immutable.
• Konflikty peerDeps: Upravte hostitelské verze, použijte overrides/resolutions nebo packageExtensions.
• Verzní drift: Fixujte rozsahy v package.json, uzamykat minor/patch dle rizika.

Výkonnostní a provozní doporučení

• Menší závislostní strom: Eliminujte těžké utility, preferujte standardní API nebo malé single-purpose moduly.
• Build v CI: Cache node a balíčků, deterministické skripty, imutabilní instalace a artefaktové repozitáře.
• Bezpečné skripty: Nepoužívejte zbytečně postinstall s nedůvěryhodným kódem, kontrolujte zdroje závislostí.

Yarn Classic vs. Yarn Berry: praktické rozdíly

• Classic (v1): Tradiční node_modules, yarn.lock, workspaces, resolutions.
• Berry (v2+): Konfigurace v .yarnrc.yml, PnP, offline cache v repozitáři, příkazy yarn up, yarn dlx, constraints a pluginový systém.
• Kompatibilita: Přepínatelný linker, cílená adopce podle potřeb projektu a nástrojového řetězce.

Bezpečnost supply chain a governance

• Review závislostí: Schvalovací seznamy, periodické aktualizace a testy kompatibility.
• Imutabilní CI a podpisy: Uzamčené prostředí, kontrola integrit a případná verifikace artefaktů.
• Privátní registry: SSO/SCIM integrace, auditní logy, retence a zrcadlení veřejného registru s filtrem.

Best practices pro týmy

• Standardizujte jeden nástroj (npm nebo Yarn) na repo, sjednoťte verze pomocí engines a .nvmrc/.node-version.
• Commitujte lockfile a v CI používejte imutabilní instalace.
• Využijte workspaces a monorepo pro sdílený kód, zamezte duplikacím a driftu verzí.
• Zaveďte audit a pravidelné aktualizace s canary releasy.
• Dokumentujte skripty a konvence; každá změna na závislostech prochází code review.

Závěr

Npm i Yarn poskytují robustní správu balíčků pro celý životní cyklus projektu: od inicializace přes vývoj a testování až po publikaci a provoz. Npm vyniká jednoduchostí a všudypřítomností, Yarn (zejména Berry) nabízí pokročilou optimalizaci, PnP a bohatý pluginový ekosystém. Volba závisí na požadavcích týmu a nástrojů, ale klíčové principy zůstávají: determinismus (lockfile), bezpečnost (audit, integrita), konzistence (engines, CI) a udržitelná správa závislostí v čase.