Slovník pojmů

npm

npm spravuje JavaScriptové závislosti a projektové skripty. Není to Node.js runtime ani totéž co veřejný npm registry; jsou to propojené, ale rozdílné vrstvy.

Stručná definice

Závislosti se deklarují, uzamykají a instalují záměrně.

npm CLI čte soubor package.json, ve kterém projekt popisuje vlastní jméno, skripty a přijatelné verze přímých závislostí. Při instalaci vyřeší také jejich nepřímé závislosti, uloží je do node_modules a obvykle vytvoří nebo upraví package-lock.json. Lockfile zachycuje konkrétní strom, ze kterého lze znovu sestavit stejné prostředí.

Node.js je runtime, který program spouští. npm je správce balíčků a nástroj pro práci s projektem. Veřejný npm registry je služba, kde jsou publikované balíčky dostupné; npm ale může pracovat i s privátním registrem, Git repozitářem, tarballem nebo lokální cestou. Proto nelze npm ztotožnit ani s Node.js, ani se samotným registrem.

Název npm se běžně čte jako en-pí-em. V dokumentaci a konverzaci může označovat CLI, veřejný ekosystém i firmu kolem registry, ale v technickém návrhu je lepší rozlišit, zda mluvíme o příkazu npm, lock souboru, registru nebo konkrétním balíčku. Ve frontendovém projektu npm typicky spouští TypeScript, Playwright i build; u PHP závislostí obdobnou, ale samostatnou roli plní Composer.

K čemu se používá

Od jedné knihovny po opakovatelný build v CI

npm propojuje deklaraci projektu, zdroje balíčků a běžné příkazy týmu. Úspěšná instalace ale sama o sobě nepotvrzuje správné chování aplikace.

přidání a aktualizace knihoven pro frontend, Node.js službu nebo vývojové nástroje
vytvoření a commitnutí package-lock.json pro opakovatelnou instalaci aplikace
spouštění týmových příkazů jako test, lint, build nebo start přes sekci scripts
oddělení runtime, vývojových, volitelných a peer závislostí podle jejich role
práce s veřejným i privátním registrem a scoped balíčky
základní kontrola známých zranitelností přes npm audit jako jedna z vrstev bezpečnosti

Praktický příklad

Projekt deklaruje záměr, lockfile drží přesný výsledek

package.json v ukázce říká, že aplikace potřebuje knihovnu express ve verzi odpovídající uvedenému semver rozsahu a že testy se spouštějí jednotným příkazem. Po řízené změně závislostí se zkontroluje také package-lock.json, protože v něm jsou přesné verze přímých i nepřímých balíčků.

Na CI nebo při nasazení aplikace se obvykle použije npm ci nad commitnutým lockfilem. Příkaz nevyhledává novou sadu verzí ani soubory package.json a package-lock.json nepřepisuje. Jestliže si odporují, skončí chybou, což je užitečnější než tiché vytvoření jiného buildu.

JSON

{
  "name": "shop-tools",
  "private": true,
  "scripts": {
    "test": "node --test",
    "build": "node scripts/build.js"
  },
  "dependencies": {
    "express": "^5.0.0"
  },
  "devDependencies": {
    "eslint": "^9.0.0"
  }
}

Jak funguje

Od deklarace závislostí ke stejnému buildu

package.json a package-lock.json mají jinou roli. Dohromady dávají týmu přehled i opakovatelnost.

package.json Projekt deklaruje přímé závislosti, verze, skripty, metadata a někdy nastavení práce s balíčky.
Řešení stromu npm vybere kompatibilní přímé i nepřímé závislosti podle deklarace, lockfile a nastavení projektu.
package-lock.json Zachytí konkrétní vyřešené balíčky, jejich zdroje a integritní údaje pro následující opakovatelnou instalaci.
node_modules a scripts Lokálně nainstalované balíčky jsou dostupné aplikaci a jejich binární nástroje mohou použít skripty v package.json.
CI a nasazení Čistá instalace z ověřeného lockfilem, testy a build vytvářejí důvěru, že jde o stejnou sadu, která prošla kontrolou.

Důležitá rozlišení

Správa balíčků není běh aplikace ani bezpečnostní prověrka.

Rozlišení vrstev pomáhá vybrat správný bezpečnostní a provozní krok.

Node.js

Runtime pro spuštění JavaScriptu mimo prohlížeč. npm se s ním často instaluje, ale nespouští aplikaci stejnou rolí jako proces node.

Registry

Služba pro publikování a stahování balíčků. npm CLI může používat veřejný registry, privátní registry i jiné zdroje balíčků.

Balíček

Distribuovatelná jednotka popsaná souborem package.json. Balíček může být knihovna, CLI nebo celá aplikace; jeho existence v registru není bezpečnostní prověrka.

Lockfile

Konkrétní vyřešený strom závislostí. Není náhradou deklarace v package.json ani zárukou, že kód balíčku je správný nebo bezpečný.

Bundler a framework

Tyto nástroje npm často instaluje a spouští přes scripts. npm ale neurčuje výsledný frontendový bundle ani architekturu aplikace.

Důležité soubory a příkazy

Instalace, lockfile a scripts nejsou zaměnitelné.

Příkaz je potřeba zvolit podle záměru: změna závislosti je jiná práce než čisté sestavení již schváleného projektu.

package.json

Je deklarace projektu a přijatelných verzí přímých závislostí. Semver rozsah jako ^5.0.0 neříká, že se vždy nainstaluje jedna pevná verze.

package-lock.json

Je konkrétní stav závislostního stromu pro aplikaci. Patří do verzovacího systému a nemá se ručně upravovat. Bez lockfile se může při další instalaci vyřešit jiná sada nepřímých závislostí.

npm install

Použij při přidání nebo řízené změně závislosti. Bez argumentu respektuje lockfile, pokud odpovídá package.json; pokud si odporují, může znovu vyřešit strom a package-lock.json aktualizovat. Není to zmrazená instalace.

npm ci

Použij pro čistou instalaci celé aplikace v CI, testu nebo nasazení. Vyžaduje lockfile, zkontroluje jeho soulad s package.json, odstraní existující node_modules a nebude zapisovat do package.json ani lockfile. Neinstaluje jednotlivý nový balíček. Vznikl-li lockfile s volbami měnícími tvar stromu, musí npm ci použít stejné volby nebo projektovou .npmrc.

scripts a binární nástroje

Sekce scripts sjednocuje příkazy týmu přes npm run. Při instalaci mohou životní cykly balíčků spouštět kód; konfigurace jako ignore-scripts sice může toto chování omezit, ale může také rozbít legitimní sestavení závislosti.

Registry a scopes

Registry je zdroj publikovaných balíčků, ne synonymum pro npm CLI. Scope například @firma/nastroj usnadňuje odlišit interní zdroj a přístupová pravidla, ale nenahrazuje kontrolu balíčku ani správu tokenů.

Výhody a omezení

Rychlý ekosystém za cenu pečlivé správy dodavatelského řetězce.

Přínosy

opakovatelný build aplikace díky lockfile
sdílené scripts pro vývoj, testy, lint a build
velký výběr knihoven a nástrojů pro JavaScriptový ekosystém
možnost oddělit veřejné a privátní zdroje balíčků

Rizika a chyby

přidání malého balíčku může přinést mnoho nepřímých závislostí i instalační kód
npm install a npm ci mají rozdílný účel; jejich záměna skrývá změny nebo rozbije čistý build
necommitnutý nebo nekonzistentní lockfile vede k rozdílným prostředím
automatické npm audit fix může změnit strom závislostí a není náhradou review
globálně instalované nástroje zhoršují opakovatelnost, pokud projekt neurčí jejich verzi

Kdy dává smysl

Pro každý udržovaný projekt s JavaScriptovými závislostmi.

npm je přirozená volba pro frontendové projekty, Node.js služby a nástroje, které potřebují spravovat knihovny, testy či build. U aplikace se package.json, package-lock.json a odpovídající konfigurace obvykle commitují společně, aby vývojář, CI a produkční build vycházely ze stejného rozhodnutí.

Nenainstaluj balíček jen proto, že zkrátí několik řádků kódu. Posuzuj aktivitu údržby, licenci, podporovanou verzi Node.js, rozsah nepřímých závislostí, instalační skripty a skutečnou hodnotu pro projekt. Malá lokální funkce může být čitelnější a bezpečnější bez dalšího balíčku.

Bezpečnost a kvalita

Instalace balíčku je spuštění změny dodavatelského řetězce.

Balíčky, konfigurace a lockfile patří do stejného review jako vlastní zdrojový kód.

commitnout package.json, package-lock.json i projektovou konfiguraci, která ovlivňuje tvar stromu závislostí
v CI a nasazení používat npm ci nad schváleným lockfilem místo obecné aktualizace
před přidáním balíčku prověřit účel, aktivitu údržby, licenci, velikost stromu a zdroj publikace
číst změny lockfile a instalačních skriptů stejně pozorně jako změnu vlastního kódu
používat npm audit pro přehled známých zranitelností, ale nález vyhodnotit podle dosažitelnosti a opravy testovat
nepouštět npm audit fix ani široký update bez review; audit fix používá instalační mechanismus a může změnit závislostní strom
chránit registry tokeny, omezit jejich oprávnění a nepředávat je nedůvěryhodným buildům či instalačním skriptům

Časté otázky

npm bez nebezpečných zkratek

Je npm totéž co Node.js?

Ne. Node.js je runtime pro běh JavaScriptu mimo prohlížeč. npm je nástroj pro správu balíčků a scripts. Často se instalují společně, ale řeší rozdílné úkoly.

Je npm totéž co npm registry?

Ne. Registry je služba, ze které se balíčky publikují a stahují. npm CLI je nástroj, který s registry může komunikovat, ale umí pracovat i s jinými registry nebo zdroji.

Jaký je rozdíl mezi npm install a npm ci?

npm install slouží i pro změnu závislostí a může aktualizovat lockfile, když není v souladu s package.json. npm ci provádí čistou, zmrazenou instalaci celého projektu z existujícího lockfile; při nesouladu skončí chybou a soubory nemění.

Má být package-lock.json v Gitu?

U aplikace obvykle ano. Zachycuje konkrétní strom, který má tým, CI i nasazení opakovat. Změna lockfile se kontroluje společně se změnou package.json.

Je npm audit důkaz, že jsou závislosti bezpečné?

Ne. Ukazuje známé zranitelnosti podle informací registru, ale neposoudí každou zranitelnost, škodlivý balíček, konfiguraci ani dosažitelnost problému. Výsledek je podklad pro review, ne bezpečnostní certifikát.

Proč mohou být instalační skripty rizikové?

Během instalace mohou spustit kód v kontextu vývojáře nebo CI. Je třeba znát zdroj balíčku, chránit tokeny a rozumět tomu, které skripty a oprávnění build skutečně potřebuje.

Jak pracuji s vývojovým prostředím

Závislosti beru jako součást bezpečného a opakovatelného nasazení.

U dlouhodobých aplikací propojuji verzování, CI, review a provozní prostředí tak, aby změna balíčku byla dohledatelná a otestovatelná.

Jak pracuji s API a integracemi Nezávazně probrat projekt