re:re:actable
Урок 011 минута чтения

Как Node.js ищет модуль при import и require?

На этой странице
Кратко

Node.js resolve-ит модуль по спецификатору импорта: встроенный модуль, относительный путь, абсолютный путь, package import или пакет из node_modules. Правила немного отличаются для CommonJS и ES Modules.

Вопрос

Как Node.js ищет модуль при import и require?

Типы спецификаторов

import fs from 'node:fs'; // встроенный модуль
import config from './config.js'; // относительный путь
import express from 'express'; // пакет из node_modules

Встроенные модули

Встроенные модули лучше импортировать с префиксом node:.

import path from 'node:path';

Так видно, что зависимость идет из Node.js, а не из npm.

Относительные импорты

В ESM обычно нужно указывать расширение файла:

import { sum } from './math.js';

CommonJS исторически умел пробовать варианты вроде .js, .json, index.js.

const { sum } = require('./math');

Пакеты

Если спецификатор не относительный и не встроенный, Node.js ищет пакет в node_modules, поднимаясь вверх по папкам проекта.

project/src/app.js
project/src/node_modules/pkg
project/node_modules/pkg
node_modules/pkg

Что важно помнить

  • Порядок: встроенный модуль → относительный или абсолютный путь → поиск в node_modules вверх по дереву каталогов.
  • В CommonJS расширение и index.js подставляются автоматически, в ESM путь указывают полностью.
  • Поле exports в package.json пакета ограничивает доступные пути.
  • require.resolve() и import.meta.resolve() показывают, какой файл будет загружен.

Мини-шпаргалка

  • node:fs - встроенный модуль.
  • ./file.js - относительный путь.
  • express - пакет.
  • ESM строже относится к расширениям.
  • package.json может менять точку входа через main и exports.

Документация

Node.js: Modules — All together, Node.js: ESM resolution algorithm.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам