Пошук уроків, статей та іншого контенту
Налаштуємо npm scripts і запускатимемо CLI-пакети для розробки, тестування та збирання проєкту.
npm scripts — це іменовані команди, описані у файлі package.json. Вони допомагають уніфікувати типові операції проєкту:
запуск застосунку в режимі розробки;
перевірка коду;
запуск тестів;
форматування;
збирання проєкту.
Приклад мінімального package.json:
{
"name": "cli-demo",
"version": "1.0.0",
"type": "module",
"scripts": {
"start": "node src/index.js",
"dev": "node --watch src/index.js",
"test": "vitest run",
"build": "esbuild src/index.js --bundle --platform=node --outfile=dist/index.js",
"format:check": "prettier --check ."
},
"devDependencies": {
"esbuild": "^0.25.0",
"prettier": "^3.5.0",
"vitest": "^3.0.0"
}
}Ключ scripts містить об’єкт, де:
ключ — назва команди;
значення — команда, яку потрібно виконати.
Запустити скрипт можна так:
npm run testДля скрипта start npm має скорочений синтаксис:
npm startТак само можна запустити npm test. Для більшості інших скриптів використовується форма npm run назва.
Створимо невеликий Node.js-проєкт:
mkdir cli-demo
cd cli-demo
npm init -y
mkdir src testВстановимо CLI-пакети як залежності для розробки:
npm install --save-dev esbuild prettier vitestПрапорець --save-dev або скорочено -D додає пакети до devDependencies.
Такі залежності потрібні під час розробки, тестування або збирання, але не обов’язково потрібні запущеному застосунку в production.
Створимо файл src/greeting.js:
export function greeting(name) {
return `Привіт, ${name}!`;
}Файл src/index.js:
import { greeting } from "./greeting.js";
console.log(greeting("Node.js"));Файл test/greeting.test.js:
import { describe, expect, it } from "vitest";
import { greeting } from "../src/greeting.js";
describe("greeting", () => {
it("повертає привітання з іменем", () => {
expect(greeting("Олена")).toBe("Привіт, Олена!");
});
});Оновимо package.json:
{
"name": "cli-demo",
"version": "1.0.0",
"private": true,
"type": "module",
"scripts": {
"start": "node src/index.js",
"dev": "node --watch src/index.js",
"test": "vitest run",
"build": "esbuild src/index.js --bundle --platform=node --outfile=dist/index.js",
"format:check": "prettier --check ."
},
"devDependencies": {
"esbuild": "^0.25.0",
"prettier": "^3.5.0",
"vitest": "^3.0.0"
}
}Тепер доступні такі команди:
npm start
npm run dev
npm test
npm run build
npm run format:checkПісля встановлення npm-пакета його виконувані команди зазвичай потрапляють до каталогу:
node_modules/.binНаприклад, пакет vitest надає команду vitest, а esbuild — команду esbuild.
Коли команда запускається через npm script, npm автоматично додає node_modules/.bin до PATH. Тому в package.json можна написати:
{
"scripts": {
"test": "vitest run",
"build": "esbuild src/index.js --bundle --outfile=dist/index.js"
}
}Не потрібно вказувати повний шлях:
{
"scripts": {
"test": "./node_modules/.bin/vitest run"
}
}Такий запис зайвий і погіршує читабельність.
Перевага локальних CLI-пакетів у тому, що всі розробники проєкту використовують версії, зафіксовані в package.json і package-lock.json.
npm startРезультат:
Привіт, Node.js!Скрипт:
{
"dev": "node --watch src/index.js"
}запускає Node.js із відстеженням змін. Після збереження файлу процес автоматично перезапускається:
npm run devnpm testЦе скорочена форма команди:
npm run testУ скрипті vitest run запускає тести один раз і завершує процес. Це зручно для CI та автоматичних перевірок.
Для інтерактивного режиму Vitest можна додати окремий скрипт:
{
"scripts": {
"test": "vitest run",
"test:watch": "vitest"
}
}Тепер:
npm run test:watchзапускатиме тести та повторюватиме їх після змін у файлах.
Скрипт:
{
"build": "esbuild src/index.js --bundle --platform=node --outfile=dist/index.js"
}використовує CLI-пакет esbuild.
Запустимо його:
npm run buildУ каталозі dist з’явиться файл index.js. Його можна виконати:
node dist/index.jsПараметри команди:
src/index.js — вхідний файл;
--bundle — об’єднати імпорти у вихідний файл;
--platform=node — враховувати середовище Node.js;
--outfile=dist/index.js — шлях до результату.
Prettier можна використовувати як CLI-пакет:
{
"scripts": {
"format": "prettier --write .",
"format:check": "prettier --check ."
}
}Команда format змінює файли:
npm run formatКоманда format:check лише перевіряє їх і повертає помилку, якщо форматування не відповідає правилам:
npm run format:checkЦе особливо корисно в автоматичних перевірках.
Аргументи для npm script передаються після подвійного дефіса --.
Наприклад, запустимо Vitest лише для певного файлу:
npm test -- test/greeting.test.jsnpm передасть усе після -- команді vitest run.
Так само можна передати параметри esbuild:
npm run build -- --minifyФактично буде виконано команду:
esbuild src/index.js --bundle --platform=node --outfile=dist/index.js --minifyЦе дає змогу не створювати окремий script для кожного варіанта запуску.
npm підтримує спеціальні скрипти, які автоматично виконуються до або після іншого скрипта.
Для скрипта build можна визначити:
prebuild — виконується перед build;
build — основна команда;
postbuild — виконується після build.
Приклад:
{
"scripts": {
"prebuild": "prettier --check src test",
"build": "esbuild src/index.js --bundle --platform=node --outfile=dist/index.js",
"postbuild": "node -e \"console.log('Збирання завершено')\""
}
}Команда:
npm run buildвиконає їх у такому порядку:
prebuild
build
postbuildЯкщо prebuild завершиться з помилкою, основний build не буде виконано.
Так можна організувати послідовність перевірок без довгого окремого shell-скрипта.
CLI-пакет можна запустити безпосередньо через npm exec:
npm exec prettier -- --check srcПісля -- передаються аргументи самому CLI-пакету.
Для локально встановленого пакета npm використає його версію з node_modules. Якщо пакет не встановлений локально, npm може запропонувати його завантажити для запуску. У командному проєкті краще явно додавати потрібний інструмент до devDependencies і запускати його через npm script.
Так:
npm run format:checkзазвичай надійніше для команди, ніж покладатися на глобально встановлений prettier.
npxnpx — звичний спосіб запуску пакетів через npm. Наприклад:
npx prettier --check srcДля сучасних npm також можна використовувати еквівалентний запис:
npm exec prettier -- --check srcУ scripts не потрібно використовувати npx для локальної залежності:
{
"scripts": {
"format:check": "prettier --check ."
}
}npm сам знайде prettier у node_modules/.bin.
Якщо виконати:
npm runбез назви команди, npm покаже список доступних scripts із package.json.
Це зручно, коли потрібно швидко дізнатися, як запускати проєкт:
Lifecycle scripts included in cli-demo:
start
node src/index.js
available via `npm run`:
build
esbuild src/index.js --bundle --platform=node --outfile=dist/index.js
dev
node --watch src/index.js
format:check
prettier --check .
test
vitest runНазви scripts варто робити короткими та передбачуваними:
start — звичайний запуск;
dev — режим розробки;
test — запуск тестів;
build — збирання;
format — форматування;
format:check — перевірка форматування.
Для пов’язаних команд використовують двокрапку: test:watch, test:coverage, format:check.
CLI-команда повідомляє про результат завершення за допомогою коду виходу:
0 — успішне виконання;
ненульове значення — помилка.
npm передає цей результат далі. Тому якщо тест або перевірка форматування завершилися помилкою, команда:
npm testтакож завершується з помилкою.
Це дозволяє автоматичним системам зрозуміти, що перевірка не пройдена.
Наприклад, такий порядок зупиниться на тестах, якщо вони не пройдуть:
{
"scripts": {
"check": "npm test && npm run format:check"
}
}Оператор && запускає другу команду лише після успішного завершення першої.
Помилка:
'vitest' is not recognizedабо:
vitest: command not foundПеревірте, чи є пакет у devDependencies:
npm install --save-dev vitestПісля цього запускайте його через npm script або npm exec.
Команда:
vitest runможе не працювати в системному терміналі, якщо каталог node_modules/.bin не доданий до глобального PATH.
Натомість використовуйте:
npm run testабо:
npm exec vitest -- runНеправильно:
npm test test/greeting.test.jsПотрібно:
npm test -- test/greeting.test.jsПодвійний дефіс відокремлює аргументи npm від аргументів самого CLI-пакета.
Скрипт:
{
"scripts": {
"tests": "vitest run"
}
}запускається так:
npm run testsА команда:
npm testшукає саме script із назвою test, а не tests.
Глобальна інсталяція:
npm install --global prettierможе створити різні версії інструментів у різних розробників.
Для проєкту краще:
npm install --save-dev prettierі script:
{
"scripts": {
"format": "prettier --write ."
}
}Так версія інструмента контролюється самим проєктом.
npm шукає package.json у поточному проєкті. Якщо запустити команду не з каталогу, де розташований цей файл, npm може не знайти script.
Перейдіть до кореня проєкту:
cd cli-demo
npm run buildnpm scripts зберігаються в полі scripts файлу package.json.
Запуск більшості scripts має форму npm run назва.
npm start і npm test — скорочені форми для стандартних scripts.
CLI-пакети можна встановлювати локально в devDependencies.
Під час виконання npm script автоматично знаходить команди з node_modules/.bin.
npm exec і npx запускають CLI-пакети без окремого script.
Аргументи передаються в script після --.
preназва і postназва дають змогу виконати команди до або після основного script.
Код завершення CLI-команди визначає, чи вважає npm операцію успішною.
Локальні версії CLI-пакетів роблять команди проєкту передбачуваними для всієї команди.