Платформа Node.js як середовище виконання

npm та package.json

Node Package Manager, структура package.json, залежності, скрипти, семантичне версіонування

npm та package.json

🎯 Мета лекції

Зрозуміти роль npm як менеджера пакетів у Node.js-екосистемі.
Опанувати структуру та призначення файлу package.json.
Розрізняти dependencies, devDependencies та peerDependencies.
Навчитися автоматизувати задачі за допомогою npm scripts.
Осмислити семантичне версіонування (semver) та оператори версій.

🔑 Ключові терміни

npm (Node Package Manager): стандартний менеджер пакетів для Node.js.
package.json: метадані проєкту: назва, версія, залежності, скрипти.
node_modules: директорія зі встановленими залежностями.
semver: система версіонування MAJOR.MINOR.PATCH.
npx: інструмент для запуску пакетів без глобального встановлення.

Ініціалізація проєкту

Кожен Node.js-проєкт починається з файлу package.json. Він описує проєкт та керує його залежностями.

# Створення package.json з інтерактивними питаннями
npm init

# Створення з типовими значеннями за замовчуванням
npm init -y

Структура package.json

{
  "name": "my-ts-app",
  "version": "1.0.0",
  "description": "TypeScript Node.js додаток",
  "type": "module",
  "main": "dist/index.js",
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js",
    "dev": "tsx src/index.ts",
    "test": "vitest"
  },
  "dependencies": {
    "express": "^4.18.0"
  },
  "devDependencies": {
    "typescript": "^5.3.0",
    "tsx": "^4.0.0",
    "@types/node": "^20.0.0",
    "@types/express": "^4.17.0",
    "vitest": "^1.0.0"
  },
  "engines": {
    "node": ">=20.0.0"
  }
}

Для TypeScript-проєктів обов'язково додавайте @types/node та @types/* для кожної бібліотеки, яка не має вбудованих типів.

Типи залежностей

Тип	Команда встановлення	Призначення
`dependencies`	`npm install <pkg>`	Пакети, необхідні для роботи додатку в продакшні
`devDependencies`	`npm install -D <pkg>`	Пакети для розробки: компілятори, тести, лінтери
`peerDependencies`	—	Залежності, які "очікуються" від батьківського пакету
`optionalDependencies`	—	Необов'язкові пакети, помилка встановлення не зупиняє npm

Практичний приклад

// dependencies — використовуються у коді додатку
import express, { type Request, type Response } from 'express';

const app = express();
app.get('/', (req: Request, res: Response) => res.json({ status: 'ok' }));

// devDependencies — використовуються лише під час розробки
// typescript, tsx, vitest, @types/* — все це devDependencies

Не встановлюйте devDependencies у продакшн-середовищі. Використовуйте npm ci --omit=dev для інсталяції лише production-залежностей.

Скрипти (scripts)

Скрипти дозволяють автоматизувати типові задачі: збірку, запуск, тестування, лінтинґ.

{
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js",
    "dev": "tsx watch src/index.ts",
    "test": "vitest run",
    "test:watch": "vitest",
    "lint": "eslint src/",
    "typecheck": "tsc --noEmit",
    "clean": "rm -rf dist"
  }
}

Запуск скриптів

# Запуск через npm run
npm run dev
npm run build
npm run test

# Деякі команди працюють без run
npm start    # еквівалент npm run start
npm test     # еквівалент npm run test

Параметри скриптів

{
  "scripts": {
    "build": "tsc",
    "preview": "node dist/server.js",
    "dev:debug": "tsx --inspect src/index.ts"
  }
}

# Передача аргументів через подвійний дефіс
npm run test -- --watch
npm run build -- --verbose

# Доступ до змінних оточення
NODE_ENV=production npm run build

Додайте npm run dev як основний спосіб запуску під час розробки. Використовуйте tsx або ts-node для виконання TypeScript без попередньої компіляції.

Семантичне версіонування (semver)

Формат: MAJOR.MINOR.PATCH

Компонент	Значення	Приклад
MAJOR	Несумісні API-зміни	`2.0.0` → `3.0.0`
MINOR	Нова функціональність (сумісна)	`1.2.0` → `1.3.0`
PATCH	Виправлення помилок (сумісне)	`1.2.3` → `1.2.4`

Оператори версій

Оператор	Значення	Приклад
`^`	Мажорна версія (зміни minor + patch)	`^4.18.0` → `>=4.18.0 <5.0.0`
`~`	Мінорна версія (зміни лише patch)	`~4.18.0` → `>=4.18.0 <4.19.0`
`>=`	Мінімальна версія	`>=20.0.0`
`*`	Будь-яка версія	`*` (не рекомендується)
`1.x`	Аналог `^1.0.0`	`1.x` → `>=1.0.0 <2.0.0`

{
  "dependencies": {
    "express": "^4.18.0",
    "lodash": "~4.17.21"
  },
  "devDependencies": {
    "typescript": "^5.3.0"
  }
}

Використовуйте ^ для залежностей додатку (більшість пакетів дотримуються semver).
Використовуйте ~ для критичних залежностей, де потрібна стабільність.
Ніколи не використовуйте * у production.

package-lock.json

Файл package-lock.json фіксує точні версії всіх встановлених залежностей та їхній деревоподібний граф.

Що зберігається в lockfile

{
  "name": "my-ts-app",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "node_modules/express": {
      "version": "4.18.2",
      "resolved": "https://registry.npmjs.org/express/-/express-4.18.2.tgz",
      "integrity": "sha512-...",
      "dependencies": {
        "body-parser": "1.20.1",
        "cookie": "0.5.0"
      }
    }
  }
}

Кращі практики

# Встановлення з lockfile (рекомендовано для CI/CD)
npm ci

# Оновлення залежностей з дотриманням semver
npm update

# Перевірка застарілих залежностей
npm outdated

Завжди додавайте package-lock.json до Git. Ніколи не ігноруйте його — він гарантує відтворюваність збірки.

npx: запуск пакетів

npx дозволяє запускати виконуваний файл пакету без його глобального встановлення.

# Запуск одноразового інструмента
npx create-ts-app my-project
npx tsx src/index.ts

# Запуск конкретної версії
npx typescript@5.3 tsc --version

# Виконання скрипту з package.json
npx vitest run

npx vs npm run

Команда	Призначення
`npx <tool>`	Запуск зовнішнього інструменту без встановлення
`npm run <script>`	Запуск скрипту з `package.json`
`npm exec <tool>`	Аналог `npx` (рідше використовується)

Альтернативи npm

Менеджер	Переваги	Встановлення
pnpm	Швидкий, економить диск, strict resolution	`npm i -g pnpm`
yarn	Кешування, offline-режим, workspaces	`npm i -g yarn`
bun	Ультрашвидкий, вбудований bundler	`curl -fsSL https://bun.sh/install \| bash`

# pnpm
pnpm install
pnpm add express
pnpm add -D typescript

# yarn
yarn install
yarn add express
yarn add -D typescript

Для нових проєктів у 2026 році рекомендується pnpm — він швидший за npm та yarn, а також гарантує строгу ізоляцію залежностей.

Резюме

✅ Ключові висновки

package.json — центральний файл конфігурації Node.js-проєкту.
Використовуйте dependencies для production та devDependencies для розробки.
Скрипти (scripts) автоматизують збірку, тестування та запуск.
Semver (MAJOR.MINOR.PATCH) та оператори ^/~ керують версіями залежностей.
package-lock.json гарантує відтворюваність — завжди додавайте його до Git.
npx дозволяє запускати інструменти без глобального встановлення.

💡 Поради для TypeScript

Завжди встановлюйте @types/node та @types/* для кожної бібліотеки.
Використовуйте "type": "module" для ESM.
Додайте скрипт "typecheck": "tsc --noEmit" для перевірки типів.
Використовуйте tsx для швидкого запуску під час розробки.

Edit this pageorReport an issue

Модульні системи: CommonJS vs ES Modules

Порівняння CommonJS та ES Modules, require vs import, module.exports vs export, інтероперабельність

Глобальні об\

global, process, console, __dirname, __filename, Buffer, setTimeout/setInterval