Пошук уроків, статей та іншого контенту
Налаштуємо package.json, визначимо метадані проєкту, залежності та npm scripts для автоматизації типових команд.
package.jsonpackage.json — це файл із описом Node.js-проєкту. Він містить:
метадані проєкту;
список залежностей;
команди для запуску через npm scripts;
вимоги до версії Node.js або npm;
додаткові налаштування інструментів.
Файл розташований у корені проєкту:
my-project/
├── package.json
├── package-lock.json
└── src/
└── index.jsСтворити базовий package.json можна командою:
npm initnpm поставить кілька запитань і сформує файл.
Для автоматичного створення з типовими значеннями використовуйте:
npm init -yТиповий package.json може виглядати так:
{
"name": "task-api",
"version": "1.0.0",
"description": "Невеликий API для роботи із завданнями",
"main": "src/index.js",
"private": true,
"license": "MIT"
}nameНазва пакета або проєкту.
Вона має:
містити лише нижній регістр;
не містити пробілів;
не починатися з крапки або символу підкреслення;
бути короткою та зрозумілою.
Наприклад:
{
"name": "task-api"
}Якщо пакет не планують публікувати в npm, назва все одно має бути коректною.
versionВерсія проєкту. Зазвичай використовується формат major.minor.patch:
{
"version": "1.0.0"
}Зміна кожної частини має умовний зміст:
major — несумісні зміни;
minor — нові можливості без порушення сумісності;
patch — виправлення помилок.
descriptionКороткий опис призначення проєкту:
{
"description": "Невеликий API для роботи із завданнями"
}mainВказує основний файл пакета:
{
"main": "src/index.js"
}Для запуску застосунку це поле саме по собі нічого не робить. Команду запуску потрібно визначити в секції scripts.
privateЯкщо значення private дорівнює true, npm не дозволить випадково опублікувати проєкт у реєстрі npm:
{
"private": true
}Це корисне налаштування для застосунків, внутрішніх сервісів і навчальних проєктів.
licenseВизначає ліцензію проєкту:
{
"license": "MIT"
}Для внутрішнього проєкту це поле може мати інше значення або бути відсутнім.
Node.js-проєкти часто використовують сторонні пакети. npm зберігає їх у двох основних секціях:
dependencies — залежності, потрібні під час роботи застосунку;
devDependencies — залежності, потрібні лише під час розробки.
Встановити пакет для роботи застосунку:
npm install expressПісля цього npm додасть пакет у dependencies.
Встановити пакет лише для розробки:
npm install --save-dev eslintСкорочений варіант:
npm i -D eslintПісля встановлення package.json може містити:
{
"dependencies": {
"express": "^5.1.0"
},
"devDependencies": {
"eslint": "^9.0.0"
}
}Наприклад:
express потрібен запущеному серверу, тому це dependencies;
тестовий раннер, лінтер або форматер потрібні під час розробки, тому це devDependencies.
Під час інсталяції проєкту npm читає package.json і встановлює перелічені пакети в директорію node_modules.
Запис:
{
"dependencies": {
"express": "^5.1.0"
}
}Символ ^ дозволяє npm встановлювати новіші сумісні версії в межах тієї самої major-версії.
Точну встановлену версію зберігає файл package-lock.json. Його потрібно додавати до системи контролю версій разом із package.json.
Для відтворення точної конфігурації залежностей у CI або на іншому комп’ютері використовують:
npm ciКоманда npm ci очікує наявність package-lock.json і встановлює залежності відповідно до нього.
Секція scripts містить команди проєкту:
{
"scripts": {
"start": "node src/index.js",
"check": "node --check src/index.js",
"test": "node --test"
}
}Назва зліва — це ім’я скрипту, а рядок справа — команда операційної системи.
Запустити скрипт можна командою:
npm run checkЗагальний формат:
npm run <script-name>Наприклад:
npm run start
npm run testДеякі назви можна запускати без run:
npm start
npm testВони відповідають таким скриптам:
{
"scripts": {
"start": "node src/index.js",
"test": "node --test"
}
}Для довільних скриптів потрібно використовувати npm run:
npm run checkПоширена структура:
{
"scripts": {
"start": "node src/index.js",
"dev": "node --watch src/index.js",
"check": "node --check src/index.js",
"test": "node --test"
}
}Призначення команд:
start — запуск застосунку;
dev — запуск у режимі розробки;
check — перевірка синтаксису;
test — запуск тестів.
Команда node --watch перезапускає файл після зміни. Вона доступна в сучасних версіях Node.js.
Створимо простий проєкт без сторонніх залежностей.
task-api/
├── package.json
├── package-lock.json
├── src/
│ └── index.js
└── test/
└── index.test.jspackage.json{
"name": "task-api",
"version": "1.0.0",
"description": "Приклад Node.js-проєкту з npm scripts",
"main": "src/index.js",
"private": true,
"type": "module",
"scripts": {
"start": "node src/index.js",
"dev": "node --watch src/index.js",
"check": "node --check src/index.js",
"test": "node --test"
},
"engines": {
"node": ">=20"
},
"license": "MIT"
}Поле type зі значенням module вказує Node.js використовувати ECMAScript modules. Завдяки цьому можна використовувати синтаксис import та export.
Поле engines описує бажану версію Node.js для проєкту:
{
"engines": {
"node": ">=20"
}
}Це метадані та рекомендація для інструментів. Саме поле не перемикає версію Node.js.
src/index.jsimport { createServer } from 'node:http';
const PORT = 3000;
const server = createServer((request, response) => {
response.writeHead(200, {
'Content-Type': 'application/json; charset=utf-8'
});
response.end(JSON.stringify({
message: 'Сервер працює',
path: request.url
}));
});
server.listen(PORT, () => {
console.log(`Сервер запущено на http://localhost:${PORT}`);
});test/index.test.jsimport test from 'node:test';
import assert from 'node:assert/strict';
test('базова арифметична операція працює', () => {
assert.equal(2 + 2, 4);
});Перевірка синтаксису:
npm run checkЗапуск тестів:
npm testЗапуск сервера:
npm startРежим розробки з автоматичним перезапуском:
npm run devПісля запуску сервера можна відкрити адресу http://localhost:3000.
npm підтримує спеціальні скрипти з префіксами pre і post.
Якщо є скрипт:
{
"scripts": {
"test": "node --test",
"pretest": "npm run check"
}
}Команда:
npm testспочатку запустить pretest, а потім test.
Так само для скрипту build npm може автоматично запускати:
prebuild — перед основною командою;
build — основна команда;
postbuild — після основної команди.
Приклад:
{
"scripts": {
"pretest": "npm run check",
"test": "node --test",
"posttest": "echo Тести завершено"
}
}У цьому прикладі порядок виконання буде таким:
перевірка синтаксису;
запуск тестів;
повідомлення про завершення.
Аргументи для команди можна передати після --.
Наприклад, скрипт:
{
"scripts": {
"test": "node --test"
}
}можна запустити з додатковим параметром:
npm test -- --watchЧастина після -- передається внутрішній команді node --test.
Це дає змогу не дублювати схожі команди в package.json.
Пакети, встановлені локально, зазвичай додають свої виконувані файли в node_modules/.bin.
Під час запуску через npm ці файли доступні без явного зазначення шляху. Наприклад:
{
"scripts": {
"lint": "eslint ."
}
}Після встановлення ESLint як devDependency команда npm run lint знайде eslint у локальному проєкті.
Це краще, ніж покладатися на глобально встановлену версію інструмента, оскільки всі учасники проєкту використовують залежність із package.json.
Оновити залежності в межах дозволених версій можна командою:
npm updateВидалити залежність:
npm uninstall expressВидалити залежність для розробки можна тією самою командою:
npm uninstall --save-dev eslintПісля цього npm оновить package.json, package-lock.json і директорію node_modules.
npm installВстановлює залежності з package.json і package-lock.json.
npm ciЧисто встановлює точні версії з lock-файла. Часто використовується в CI.
npm runПоказує доступні npm scripts.
npm list --depth=0Показує безпосередні залежності проєкту.
npm outdatedПоказує залежності, для яких доступні новіші версії.
Для скрипту з довільною назвою:
{
"scripts": {
"check": "node --check src/index.js"
}
}потрібно використовувати:
npm run checkКоманда npm check не є еквівалентною.
Не варто покладатися на глобальну інсталяцію лінтера або тестового раннера:
npm install -g eslintКраще встановити інструмент у конкретний проєкт:
npm install --save-dev eslintТак версія інструмента буде зафіксована в package.json і доступна іншим розробникам.
package-lock.json у репозиторіїpackage.json може дозволяти діапазон версій, а package-lock.json фіксує конкретні версії.
Для застосунків і бібліотек lock-файл зазвичай потрібно зберігати в системі контролю версій.
package.json — це JSON-файл, тому в ньому:
ключі та рядкові значення беруться в подвійні лапки;
після останньої властивості не ставиться кома;
коментарі не дозволені.
Некоректно:
{
"name": "task-api",
}Коректно:
{
"name": "task-api"
}devDependenciesЯкщо застосунок імпортує пакет під час роботи, пакет має бути в dependencies:
{
"dependencies": {
"express": "^5.1.0"
}
}Інструменти, потрібні лише для перевірки, тестування або форматування коду, належать до devDependencies.
package.json описує Node.js-проєкт і його залежності.
Метадані на кшталт name, version, description та license роблять проєкт зрозумілим.
dependencies містить пакети, потрібні під час роботи застосунку.
devDependencies містить інструменти для розробки.
scripts зберігає повторювані команди проєкту.
Довільні npm scripts запускають через npm run <name>.
npm start і npm test можна запускати без run.
package-lock.json фіксує точні версії залежностей.
Локальні версії інструментів надійніші за глобально встановлені.