NPM: Průvodce začátky a základními příkazy

NPM (Node Package Manager) je správce javascriptových balíčků. Usnadňuje jejich instalaci a následnou údržbu. Jde tedy o obdobu například Composeru ze světa PHP.

Čím se v tomhle článku pro začínající, mírně pokročilé a v NPM plavající pokročilé budeme zabývat?

• Historie a konkurence
• Instalace a aktualizace
• Struktura souborů a adresář
• Základní příkazy

Historie a konkurence

Původně NPM vymysleli pro správu balíčků k serverovému Javascriptu – Node.js. To se časem přeneslo na spouštění různých užitečných nástrojů na příkazové řádce – například pomocí Gruntu nebo Gulpu.

Nakonec ale NPM spravuje i frontendový Javascript a dnes už (po uzavření Boweru) i jakékoliv frontendové balíčky.

Pokročilejší vývojáři často namísto NPM používají nástroj Yarn, ale o tom napíšu jindy. Základní použití Yarnu je plus minus podobné a používá i totožné balíčky a stejnou konfiguraci.

Samozřejmě je zde i řada alternativ pro ty z vás, kteří se nechcete zabývat příkazovou řádkou. Alespoň pro úkoly spojené s automatizací vývojářské práce. Pro vývojáře nepracující v týmu je zde například Prepros a na Macu populární Codekit.

Instalace a aktualizace

NPM si nainstalujte i s celým Node.js. Jděte na následující adresu a stáhněte si LTS (Long Term Support) verzi: nodejs.org/en/.

Ve zvláštním článku na Vzhůru dolů je o instalaci Node více informací.

Otevřete příkazovou řádku a ověřte, zda je vše v pořádku:

$ npm --version

Mělo by to vrátit:

6.1.0

Vaše verze se může lišit, ale pokud je menší než 5, doporučuji aktualizaci. Když už jednou máte NPM, můžete tenhle nástroj poprosit, aby aktualizoval sám sebe:

npm install npm@latest -g

Přikazujeme tím nástroji npm, aby aktualizoval (install) sebe sama do poslední verze (@latest). A aby se instalovalo globálně pro celý počítač (-g). NPM totiž chceme v příkazové řádce používat z jakékoliv složky.

Nepotřebujete sudo?

Na Macu a Linuxu může být potřeba instalovat s administrátorským oprávněním (sudo):

sudo npm install npm@latest -g

Opět odkážu na článek o instalaci Node, kde se tomu věnuji více.

Struktura souborů a adresářů

Mrkněme se společně na strukturu souborů a adresářů projektu:

node_modules/
package.json
package-lock.json

• node_modules/ je složka, do které se instalují balíčky. Ta se jako jediná nenahrává do Gitu nebo jiného verzovacího systému, protože by zbytečně zabírala prostor a celkově dělala ohromný nepořádek.
• package.json v kořenovém adresáři je soubor s konfigurací NPM. Obsahuje informace o projektu a seznam potřebných balíčků. Více ve zvláštním textu.
• package-lock.json uchovává informace o instalovaných verzích balíčků, aby to bylo jednotné pro všechny, kteří na projektu pracují. I tady píšu více ve zvláštním textu.

Pojďme se teď podívat ale na hlavní část článku – základní příkazy, které se mohou hodit opravdu každému webovému vývojáři a webové vývojářce.

Základní příkazy

Příkaz	Co dělá
npm init	Vytvoří projekt
npm search	Vyhledá balíčky
npm install	Instaluje balíčky
npm uninstall	Odinstaluje balíčky
npm list	Výpis stromu závislostí
npm outdated	Seznam balíčků k aktualizaci
npm update	Aktualizuje verzi balíčků
npm help	Nápověda

npm init: Vytvoří projekt

Projekt může vznikat zkopírováním souboru package.json z jiného a jeho manuální úpravou. Můžete ale odstartovat úplně z nuly:

npm init

Spustí to dotazník, kde budete muset vyplnit název projektu („package name“), jeho verzi, popis, autora a tak dále. Může vám stačit ponechat výchozí hodnoty – použijte npm init --yes a příkaz vás nebude zatěžovat otázkami.

Vytvoříme tak soubor package.json:

{
  "name": "npm",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

Zatím na něm není nic moc zajímavého. Pojďme si přidat nějaké balíčky, které budeme na projektu používat.

npm search: Vyhledá balíček

npm search <název-balíčku>

Řekněme, že bychom na projektu chtěli mít knihovnu Bootstrap. Její přesný název si můžeme najít dvěma cestami:

• Přes web: npmjs.com/search?q=bootstrap
• Přes NPM: npm search bootstrap.

Druhý uvedený nám do příkazové řádky vrátí seznam možností:

NAME                       | DESCRIPTION          | AUTHOR           | DATE       | VERSION  | KEYWORDS
bootstrap                  | The most popular…    | =mdo =twbs       | 2018-07-24 | 4.1.3    | css sass mobile-first res
react-bootstrap            | Bootstrap 3…         | =monastic.panic… | 2018-09-06 | 0.32.4   | react ecosystem-react re
@ng-bootstrap/ng-bootstrap | Angular powered…     | =ng-bootstrap    | 2018-10-26 | 4.0.0    | angular bootstrap compone

Vybereme hned tu první. Pojďme teď Bootstrap nainstalovat.

npm install: Instaluje balíček

npm install (<název-balíčku>)

Instalovat Bootstrap můžeme tedy následovně:

npm install bootstrap

Načež se nám vrátí něco podobného:

npm WARN [email protected] No description
npm WARN [email protected] No repository field.
npm notice created a lockfile as package-lock.json. You should commit this file.
npm WARN [email protected] requires a peer of [email protected] - 3 but none is installed. You must install peer dependencies yourself.
npm WARN [email protected] requires a peer of popper.js@^1.14.3 but none is installed. You must install peer dependencies yourself.

+ [email protected]
added 1 package from 2 contributors and audited 1 package in 2.949s
found 0 vulnerabilities

Pojďme si to rozebrat:

NPM upozorňuje („WARN“), že nám v souboru package.json chybí obsah v polích „description“ a „repository“. Na soukromém uzavřeném projektu nám to nemusí vadit, ale obecně je lepší si tyto políčka vyplnit.

Dále je zde informace, že NPM vytvořilo soubor package-lock.json („created a lockfile as package-lock.json“), což je v pořádku. Když si ten soubor prohlédnete, asi budete souhlasit, že jej mají spravovat stroje, nikoliv lidé.

Nakonec nám NPM poskytuje laskavé upozornění („WARN“): Aby Bootstrap správně fungoval, potřebuje následující balíčky: jQuery a Popper.

Odbočka: „Peer“ závislosti

Jelikož jde o takzvané „peer dependencies“, tedy závislost balíčků na stejné úrovni, neinstaluje je balíčkovací systém sám, ale musíme o udělat my. Více o závislostech píšu v textu o package.json.

Takže vzhůru do toho:

npm install jquery popper.js

Dostaneme pak něco takového:

+ [email protected]
+ [email protected]
added 1 package from 2 contributors, updated 1 package and audited 7615 packages in 6.813s
found 0 vulnerabilities

Kromě informace o nainstalovaných balíčcích (např. „jquery“) a jejich verzích („3.3.1“) je zde také zpráva, že NPM v balíčcích nenalezlo žádné bezpečnostní zranitelnosti („found 0 vulnerabilities“), takže můžeme být klidní.

Důležité je vědět, že existuje možnost použít příkaz bez názvu balíčku:

npm install

V takovém případě se stáhnou a uloží nové verze balíčků podle předpisu z definičního souboru package.json.

npm uninstall: Odstraní balíček

Samozřejmě je zde i možnost odstraňovat balíčky z projektu:

npm uninstall popper.js

NPM pak provede následující:

1. Odstraní adresář popper.js z node_modules.
2. Odmaže jeho výskyt z package.json a package-lock.json

Na tom nic složitého není, takže pojďme na další příklad.

npm list: Výpis stromu závislostí

Funguje to asi takhle:

npm list --depth=<číslo>

<číslo> udává hloubku výpisu. To je dost zásadní, protože npm list by nám vypsal ohromnou strukturu všech závislostí. Spokojíme se s prvními dvěma úrovněmi:

npm list --depth=0

Dostaneme:

├── [email protected]
├── [email protected]
└── [email protected]

To je vlastně totéž co aktuálně obsahuje adresář node_modules/. A totéž co sekce závislostí v našem milém souboru package.json:

"dependencies": {
  "bootstrap": "^4.1.3",
  "jquery": "^3.3.1",
  "popper.js": "^1.14.4"
}

Co znamenají ty stříšky? Možnost aktualizovat minor a patch verze, tedy druhé a třetí číslo. Více o způsobu verzování a nastavování závislostí v package.json najdete v článku o SemVer, sémantickém verzování.

npm outdated: Seznam balíčků k aktualizaci

Představme si, že máme v souboru package.json následující:

"dependencies": {
  "bootstrap": "~3.3.6",
}

A položíme dotaz na zastaralé verze balíčků:

npm outdated

Výstup:

Package                     Current  Wanted   Latest  Location
bootstrap                     3.3.6   3.3.7    4.1.3

Říká nám to, že aktuálně máme nainstalovánu verzi 3.3.6 („Current“), přičemž podle předpisu z package.json můžeme pomocí příkazu npm install aktualizovat na verzi 3.3.6 („Wanted“).

Zároveň ale je dobré vědět, že nejnovější verze Bootstrapu je 4.1.3 („Latest“). Ta se ale v našem případě nestáhne, dokud to doslovně nepovolíme v package.json - například takto:

"dependencies": {
  "bootstrap": "^4.1.3",
}

Vidíte, že jsem zápis změnil na stříšku, což obecně doporučuji. Více je v textu o SemVer.

npm update: Aktualizace verzí balíčků

npm update (<název-balíčku>)

Tenhle příkaz slouží k aktualizaci instalované verze jednoho nebo úplně všech balíčků na nejnovější verzi vyhovující předpisu ze souboru package.json. To je věc, kterou už u nainstalovaných balíčků nedělá npm install.

Jen pro pořádek dodávám, že:

• npm update nahraje nové verze všech lokálních balíčků.
• npm update -g aktualizuje všechny globální balíčky.

Tenhle příkaz záměrně uvádím až na konci textu, protože pro začátečníky bude matoucí koexistence s npm install. Velmi často se bez npm update můžete obejít.

Příklad použití

V předchozím textu jsme bez tohoto příkazu mohli žít, protože jsme si vystačili s následujícím procesem:

• npm install nainstaluje balíčky.
• npm outdated hlídá nové verze.
• Aktualizaci verzí děláme úpravou package.json a novým spuštěním npm install.

Tohle nám ale nemusí vyhovovat. Prostě to můžeme chtít udělat příkazem. Vezměme, že se v našem příkladu změnila verze balíčku Popper.js:

npm outdated

Vrací:

Package    Current  Wanted  Latest  Location
popper.js   1.14.4  1.14.5  1.14.5  npm

Když bychom chtěli aktualizovat a dali npm install, ten se spokojí s instalovanou verzí, protože vyhovuje předpisu v package.json.

Proto pojďme aktualizovat balíčky:

npm update

Vrátí:

+ [email protected]
updated 1 package and audited 4 packages in 1.366s
found 0 vulnerabilities

Stáhne tedy novou verzi, uloží ji do adresáře node_modules/ a co je důležité – změní soubor package-lock.json. Ten, jak už víme, obsahuje informace o reálně instalovaných verzích balíčků. Změny v něm pak commitneme do repozitáře a máme aktualizováno.

Jak už název příkazů napovídá, npm install používejte pro instalaci nových balíčků, npm update pak pro aktualizaci na poslední dostupné verze podle předpisu zápisem SemVer v package.json.

npm help: Nápověda

Nápovědu můžete získat různými způsoby:

• npm help – nápověda k nápovědě.
• npm <příkaz> --help (např. npm install --help) – stručná nápověda k příkazu.
• npm help <příkaz> (např. npm help install) – detailní nápověda k příkazu.)

Jo – a je dobré vědět, že z nápovědy na příkazové řádce se dá vylézt pomocí klávesy q.

To je prozatím vše. Ať se vám s NPM pracuje dobře.

Více informací:

• Dokumentace NPM
• Soubory: package.json a package-lock.json
• Školení Nástroje Javascriptu