Správa balíčků pomocí npm a Yarn: závislosti a verze

Backend, PHP a serverové skriptování
P. Varga
Správa balíčků s npm a Yarn: Závislosti a verze

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, workspaces v monorepech 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

  • Registr: Výchozím je veřejný registr npm. Lze využít privátní registry a proxy (např. Verdaccio, Nexus, Artifactory) pro ukládání do mezipaměti a řízení přístupu.
  • Resolver: Řeší strom závislostí podle pravidel semver, peer závislostí a rozlišení přímých a tranzitivní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, respektive yarn install. Přidání balíčku: npm i react nebo yarn add react.
  • Odstranění: npm uninstall oproti yarn remove; aktualizace: npm update oproti 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 jeho verze podle semver.
  • scripts: Příkazy spouštěné přes npm run nebo yarn (např. build, test, start).
  • dependencies, devDependencies: Běhové a vývojové závislosti.
  • peerDependencies, optionalDependencies: Závislosti pro pluginy a volitelné funkce s mírnější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 deklarace typů.

Semver a rozsahy verzí

  • Major.Minor.Patch: 1.2.3; major může obsahovat změny narušující zpětnou kompatibilitu, minor přidává funkce a patch opravuje chyby.
  • Rozsahy: ^1.2.3 povoluje minor/patch, ~1.2.3 pouze patch; pevné připnutí verze minimalizuje drift.
  • Předběžná verze: 1.2.3-beta.1 vyžaduje explicitní povolení v resolveru.

Lockfile: deterministická reprodukovatelnost

  • npm: package-lock.json uzamyká přesné verze a kontrolní součty integrity.
  • Yarn: yarn.lock (Classic) nebo yarn.lock s metadaty Berry; verze lockfile se mezi generacemi liší.
  • Praxe: Zařazujte do VCS, ručně neupravujte a při změně registru zneplatněte. V CI používejte npm ci nebo yarn install --immutable pro přísnou konzistenci.

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

  • Model node_modules: Tradiční fyzický strom závislostí, kompatibilní se všemi nástroji; může být rozsáhlý a obsahovat duplicity.
  • Yarn PnP: Virtuální mapování bez node_modules; rychlejší instalace a rozlišení závislostí; vyžaduje kompatibilitu nástrojů a PnP loader.
  • Volba linkeru: Yarn umožňuje přepnout na nodeLinker: node-modules kvůli kompatibilitě.

Workspaces a monorepo

  • npm workspaces: Definice balíčků v monorepu, sdílený lockfile a lokální propojení balíčků.
  • Yarn workspaces: Pokročilé funkce (constraints, protocache, yarn workspaces foreach), podrobné řízení spouštění skriptů a paralelizace.
  • Doporučený postup: Jeden lockfile v kořenovém adresáři, 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 hooky: prebuild, postbuild, prepare (užitečné pro instalace založené na Git), prepublishOnly pro kontrolu před publikací.
  • Orchestrace: Paralelní běh 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ř. plugin pro React vyžaduje React v určité verzi).
  • npm: Moderní npm může peer závislosti automaticky instalovat pouze za určitých podmínek, odpovědnost však stále nese hostitel.
  • Yarn: Berry nabízí pravidla rozlišení a položky resolutions nebo packageExtensions pro nápravu chyb v cizích balíčcích.

Resolutions, overrides a deduplikace

  • npm overrides: Sekce overrides vynucuje konkrétní verze tranzitivních závislostí.
  • Yarn resolutions: Pole resolutions (Classic) a pokročilejší constraints (Berry) definující pravidla pro závislosti.
  • Deduplikace: npm dedupe nebo yarn dedupe zmenší strom a sníží jeho prostorovou náročnost.

Cache, výkon a determinismus v CI

  • Adresáře cache: Cache ~/.npm, ~/.cache/yarn a případně .yarn/cache (Berry) mezi běhy CI.
  • Neměnné instalace: npm ci a yarn install --immutable --check-cache zajistí shodu s lockfile.
  • Offline instalace: Yarn Berry umožňuje plně offline instalaci 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 auditovat registr npm příkazem yarn npm audit (Berry) nebo pomocí pluginů.
  • Integrita: Kontrolní součty v lockfile brání podvržení artefaktů; doporučuje se ověřovat integritu v CI.
  • Tokeny a 2FA: K publikaci a přístupu k soukromým registrům slouží přístupové tokeny; doporučuje se povolit dvoufaktorové ověřování.

Publikace balíčků

  • npm publish: Publikuje podle položek files, .npmignore a publishConfig. Štítky (dist-tags), jako latest a next, umožňují bezpečné postupné nasazování.
  • Yarn: Ve verzi Classic využívá yarn publish (obal nad npm); Berry nabízí yarn npm publish a správu verzí pomocí yarn version.
  • Monorepo: Verzování balíčků koordinujte nástroji typu Changesets, případně pluginy Yarn version.

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

  • Duální publikace: Exportní pole exports s podmínkami pro ESM/CJS, pole type: module a kompatibilní položky main/module.
  • Typy: Položka types a sdružování deklarací pro TypeScript, případně jejich generování pomocí tsc nebo nástrojů pro sestavení.

Migrace mezi npm a Yarn

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

Konfigurace a správa registrů

  • .npmrc a .yarnrc.yml: Nastavení registrů, tokenů, always-auth, zásad pro cache a audity.
  • Registr pro konkrétní scope: Např. @company:registry=https://registry.example.com pro interní balíčky.

Diagnostika a řešení problémů

  • Čistá instalace: Smažte node_modules a lockfile, poté spusťte npm ci nebo yarn install --immutable.
  • Konflikty peerDeps: Upravte verze hostitelských balíčků, použijte overrides/resolutions nebo packageExtensions.
  • Odchylky verzí: Upravte rozsahy v package.json a podle míry rizika uzamkněte minor/patch verze.

Doporučení pro výkon a provoz

  • Menší strom závislostí: Omezte používání náročných knihoven nástrojů a upřednostňujte standardní API nebo malé moduly s jediným účelem.
  • Sestavování v CI: Ukládejte do cache Node.js a balíčky, používejte deterministické skripty, neměnné instalace a repozitáře artefaktů.
  • Bezpečné skripty: Nepoužívejte zbytečně postinstall s nedůvěryhodným kódem a 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 systém pluginů.
  • Kompatibilita: Přepínatelný linker a cílené zavádění podle potřeb projektu a nástrojového řetězce.

Zabezpečení dodavatelského řetězce a správa

  • Kontrola závislostí: Seznamy schválených závislostí, pravidelné aktualizace a testy kompatibility.
  • Neměnné CI a podpisy: Uzamčené prostředí, kontrola integrity a případné ověřování artefaktů.
  • Soukromé registry: Integrace SSO/SCIM, auditní logy, doba uchovávání a zrcadlení veřejného registru s filtrováním.

Doporučené postupy pro týmy

  • Standardizujte jeden nástroj (npm nebo Yarn) pro každý repozitář a sjednoťte verze pomocí engines a .nvmrc/.node-version.
  • Zařazujte lockfile do verzovacího systému a v CI používejte neměnné instalace.
  • Využívejte workspaces a monorepo pro sdílení kódu a předcházejte duplicitám a odchylkám verzí.
  • Zaveďte audit a pravidelné aktualizace s canary releasy.
  • Dokumentujte skripty a konvence; každou změnu závislostí podrobte kontrole kódu.

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ý ekosystém pluginů. Volba závisí na požadavcích týmu a nástrojů, klíčové principy však zůstávají stejné: determinismus (lockfile), bezpečnost (audit, integrita), konzistence (engines, CI) a udržitelná správa závislostí v čase.