Node.js с нуля: модули, npm и первый сервер

В уроке «Что такое backend» мы разобрали, что делает сервер. Теперь — инструмент, на котором этот сервер можно написать, не уходя из JavaScript. Node.js — открытая кроссплатформенная среда выполнения JavaScript. Внутри неё работает V8 — тот же движок, что исполняет JavaScript в Chrome, — но снаружи нет браузера: нет document, window и DOM. Вместо них — стандартная библиотека для работы с файлами, сетью, процессами и потоками данных.

Документация Node.js подчёркивает главную особенность: приложение работает в одном процессе и не создаёт поток на каждый запрос. Операции ввода-вывода — чтение файла, запрос к базе, обращение к сети — неблокирующие: пока ответ не пришёл, Node.js обслуживает другие запросы, а затем возвращается к вашему коду через промис или колбэк. Это та же модель цикла событий, которую вы видели в уроке об асинхронном JavaScript, только применённая к серверу.

Важное следствие из последней строки таблицы: код на сервере видит ваши ключи, базу и файловую систему, поэтому всё, что вы читаете из запроса, нужно проверять. Для уроков используйте актуальную LTS-ветку — версию с долгосрочной поддержкой. На дату проверки это Node.js 24 (кодовое имя Krypton); код урока проверен на 24.18. Проверьте свои версии:

$ node -v
v24.18.0
$ npm -v
11.16.0

Любой проект на Node.js — это папка с файлом package.json: в нём имя, версия, скрипты запуска и список зависимостей. Создаёт его команда npm init, а ключ -y принимает значения по умолчанию без вопросов. Дальше удобно править файл не руками, а через npm pkg set — так не сломаете JSON. Создадим проект API со списком услуг:

mkdir services-api
cd services-api
npm init -y
npm pkg set type=module
npm pkg set scripts.dev="node --watch --env-file=.env server.js" scripts.start="node server.js"
npm pkg set private=true --json
npm pkg delete scripts.test main

{
  "name": "services-api",
  "version": "1.0.0",
  "description": "",
  "scripts": {
    "dev": "node --watch --env-file=.env server.js",
    "start": "node server.js"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "type": "module",
  "private": true,
  "dependencies": {
    "zod": "^4.6.6"
  }
}

• "type": "module" — файлы .js в проекте считаются ES-модулями. npm 11 по умолчанию записывает "type": "commonjs" (настройка init-type), поэтому значение меняем явно. Документация Node.js советует всегда указывать поле type, а не полагаться на автоопределение
• "private": true — npm откажется публиковать проект в реестр: для приложения, в отличие от библиотеки, это защита от ошибки
• scripts — команды проекта. npm run dev запустит сервер для разработки, npm start — без флагов разработки. Начиная с Node.js 22 скрипты можно запускать и встроенной командой node --run dev

Пакеты из реестра npm ставит npm install <имя>. Установим Zod — библиотеку валидации, которая понадобится в следующем уроке про Express:

$ npm install zod

added 1 package, and audited 2 packages in 2s

1 package is looking for funding
  run `npm fund` for details

found 0 vulnerabilities

$ npm pkg get dependencies
{
  "zod": "^4.6.6"
}

$ npm ls
services-api@1.0.0 …/services-api
`-- zod@4.6.6

Модуль — файл со своей областью видимости: наружу видно только то, что вы явно экспортировали. Node.js поддерживает две системы модулей. CommonJS с require() — историческая, её вы встретите в старых проектах и примерах. ES-модули с import и export — стандарт языка, тот же, что в браузере. Новые проекты пишут на ES-модулях. Вынесем настройки и загрузку данных в отдельные модули:

const port = Number(process.env.PORT ?? 8080);

if (!Number.isInteger(port) || port < 1 || port > 65535) {
  throw new Error(`PORT must be an integer from 1 to 65535, got "${process.env.PORT}"`);
}

export const config = {
  port,
  host: process.env.HOST ?? "127.0.0.1",
  appName: process.env.APP_NAME ?? "services-api",
};

import { readFile } from "node:fs/promises";
import { join } from "node:path";

const file = join(import.meta.dirname, "..", "data", "services.json");

export async function loadServices() {
  const text = await readFile(file, "utf8");
  return JSON.parse(text);
}

[
  { "id": "web", "title": "Сайт для бизнеса", "category": "web" },
  { "id": "crm", "title": "CRM-система", "category": "software" },
  { "id": "bot", "title": "Telegram-бот", "category": "integrations" }
]

• Встроенные модули импортируют с префиксом node: — node:fs/promises, node:http. Так сразу видно, что это не пакет из npm с похожим именем
• В относительном импорте расширение файла обязательно: ./src/config.js, а не ./src/config — так требует документация ESM, как и в браузере
• require, __dirname и __filename в ES-модулях не определены. Вместо двух последних — import.meta.dirname и import.meta.filename, стабильные с Node.js 24
• await можно писать на верхнем уровне модуля, без обёртки в async-функцию — им мы загрузим данные до старта сервера

$ node a.mjs        # import { config } from "./config"
Error [ERR_MODULE_NOT_FOUND]: Cannot find module '…/config' imported from …/a.mjs
Did you mean to import "./config.js"?

$ node b.mjs        # const fs = require("node:fs")
ReferenceError: require is not defined in ES module scope, you can use import instead

$ node c.mjs        # console.log(__dirname)
ReferenceError: __dirname is not defined in ES module scope

Стандартная библиотека Node.js покрывает большую часть задач простого сервера — без единой зависимости. В src/services.js уже работают два модуля: readFile из node:fs/promises читает файл и возвращает промис, а join из node:path склеивает путь с правильными разделителями для Windows и Unix. Используйте промисную версию fs: синхронные функции вроде readFileSync останавливают весь процесс, пока диск не ответит, и на сервере допустимы разве что при старте.

Модуль node:events стоит понять сразу, потому что на нём построена половина Node.js: HTTP-сервер, запрос, ответ, потоки — всё это объекты EventEmitter. Один объект генерирует событие методом emit, а подписчики, зарегистрированные через on, вызываются по очереди, синхронно. Так удобно развязывать код: модуль заказов не знает, кто будет слать письма и считать статистику.

import { EventEmitter } from "node:events";

const orders = new EventEmitter();

orders.on("created", (order) => console.log(`email: order #${order.id} received`));
orders.on("created", (order) => console.log(`stats: +${order.total} KZT`));
orders.once("created", () => console.log("first order today!"));

orders.emit("created", { id: 1, total: 12000 });
orders.emit("created", { id: 2, total: 8500 });
console.log("listeners:", orders.listenerCount("created"));

orders.emit("error", new Error("payment service timeout"));
console.log("this line is never printed");

$ node events-demo.js
email: order #1 received
stats: +12000 KZT
first order today!
email: order #2 received
stats: +8500 KZT
listeners: 2
…/events-demo.js:13
orders.emit("error", new Error("payment service timeout"));
                     ^

Error: payment service timeout
    at …/events-demo.js:13:22
Emitted 'error' event at:
    at …/events-demo.js:13:8

Node.js v24.18.0

Устройство запросов и ответов, заголовки и коды мы подробно разобрали в уроке «HTTP и JSON», где на node:http уже был сервер заказов. Здесь сервер собирается из модулей проекта и получает две вещи, без которых не обходится ни один backend: журнал запросов и обработку ошибки запуска. Маршрутов два: GET /health — проверка, что процесс жив (её опрашивают хостинг и балансировщик), и GET /services — список услуг из файла.

import { createServer } from "node:http";
import { config } from "./src/config.js";
import { loadServices } from "./src/services.js";

const services = await loadServices();

function sendJson(res, status, data, headers = {}) {
  const body = JSON.stringify(data);
  res.writeHead(status, {
    "Content-Type": "application/json; charset=utf-8",
    "Content-Length": Buffer.byteLength(body),
    ...headers,
  });
  res.end(body);
}

const routes = {
  "/health": () => ({ status: "ok", uptime: Math.round(process.uptime()) }),
  "/services": () => services,
};

const server = createServer((req, res) => {
  const started = performance.now();
  res.on("finish", () => {
    const ms = (performance.now() - started).toFixed(1);
    console.log(`${req.method} ${req.url} ${res.statusCode} ${ms}ms`);
  });

  const { pathname } = new URL(req.url, "http://localhost");
  const route = routes[pathname];
  if (!route) return sendJson(res, 404, { error: "Not found" });
  if (req.method !== "GET") {
    return sendJson(res, 405, { error: "Method not allowed" }, { Allow: "GET" });
  }
  sendJson(res, 200, route());
});

server.on("error", (error) => {
  console.error(`Cannot start server: ${error.code} ${error.message}`);
  process.exit(1);
});

server.listen(config.port, config.host, () => {
  console.log(`${config.appName}: http://${config.host}:${config.port}`);
});

Запустите npm run dev и во втором терминале отправьте запросы:

$ curl -si http://127.0.0.1:8080/health
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 26
Date: Sun, 11 Oct 2026 23:13:57 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"status":"ok","uptime":1}

$ curl -s http://127.0.0.1:8080/services
[{"id":"web","title":"Сайт для бизнеса","category":"web"},{"id":"crm","title":"CRM-система","category":"software"},{"id":"bot","title":"Telegram-бот","category":"integrations"}]

$ curl -si -X POST http://127.0.0.1:8080/services
HTTP/1.1 405 Method Not Allowed
Content-Type: application/json; charset=utf-8
Content-Length: 30
Allow: GET
Date: Sun, 11 Oct 2026 23:13:57 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"error":"Method not allowed"}

$ curl -s http://127.0.0.1:8080/price
{"error":"Not found"}

Порт, адрес базы, ключи сервисов отличаются между ноутбуком, тестовым и боевым сервером, поэтому их не пишут в код, а читают из переменных окружения — объекта process.env. Для разработки их удобно держать в файле .env, а Node.js умеет загрузить его сам, без пакета dotenv: флаг --env-file стабилен с версии 24.10.

PORT=8080
HOST=127.0.0.1
APP_NAME=InterLAB services API

node_modules/
.env

$ node server.js
services-api: http://127.0.0.1:8080

$ PORT=8081 node --env-file=.env server.js
InterLAB services API: http://127.0.0.1:8081

$ PORT=abc node server.js
Error: PORT must be an integer from 1 to 65535, got "abc"
    at …/src/config.js:4:9

$ node --env-file=.env.local server.js
C:\Program Files\nodejs\node.exe: .env.local: not found

$ node --env-file=.env server.js   # second instance, port already in use
Cannot start server: EADDRINUSE listen EADDRINUSE: address already in use 127.0.0.1:8080

• Все значения из окружения — строки. PORT=8080 придёт как "8080", поэтому config.js переводит его в число и проверяет диапазон. Ошибку конфигурации лучше получить при старте, чем при первом запросе
• Если переменная задана и в окружении, и в файле, побеждает окружение — так на сервере можно переопределить значение из .env
• --env-file завершает процесс, если файла нет. Для необязательного файла есть --env-file-if-exists, а из кода — process.loadEnvFile()
• Секреты в продакшене задают средствами хостинга или менеджера секретов, а не файлом рядом с кодом. Подробнее — в уроке о секретах и переменных окружения

Флаг --watch перезапускает процесс, когда меняется точка входа или любой импортированный модуль, — в логе выше это строка Restarting 'server.js'. Проверка на Node.js 24.18 показала: перезапуск срабатывает и при изменении файла из --env-file, но не при правке data/services.json — файл читается через fs, а не импортируется. Чтобы следить за произвольными папками, используйте --watch-path=.; учтите, что этот флаг отключает автоматическое отслеживание импортов, поэтому указывайте папки целиком.

$ npm run dev

> services-api@1.0.0 dev
> node --watch --env-file=.env server.js

InterLAB services API: http://127.0.0.1:8080
GET /health 200 2.4ms
GET /services 200 0.3ms
POST /services 405 0.3ms
GET /price 404 0.3ms
Restarting 'server.js'
InterLAB services API: http://127.0.0.1:8080
GET /services 200 2.7ms

Сервер работает, но посмотрите, сколько пришлось сделать руками: сравнивать пути, вытаскивать параметры регулярным выражением, собирать JSON-ответ, помнить про 405. Для POST добавятся чтение тела, разбор JSON, проверка Content-Type, валидация и единый формат ошибок — в уроке «HTTP и JSON» это заняло десятки строк на один маршрут. Именно это берёт на себя фреймворк. В следующем уроке перенесём API на Express: маршруты с параметрами, middleware, валидация через Zod и центральный обработчик ошибок.