Указание версии Node.js в package.json для проекта

Вы можете указать требуемую версию Node.js в файле package.json с помощью поля engines. По умолчанию это поле является только советом и выводит предупреждения, но вы можете принудительно проверять версии, установив engine-strict=true в файле .npmrc, что заставит команды npm завершаться с ошибкой, если версии не совпадают.

Содержание

• Использование поля engines
• Принудительная проверка версий
• Синтаксические примеры
• Альтернативные подходы
• Лучшие практики

Использование поля engines

Основной способ указать требования к версии Node.js в package.json — это поле engines. Это поле позволяет определить, какие версии Node.js (и при желании npm) поддерживает ваш проект.

Согласно официальной документации npm, поле engines по умолчанию является только советом, если пользователь не установил флаг конфигурации engine-strict. Это означает, что при установке пакета в качестве зависимости будет выводиться только предупреждение.

Для требования Node.js версии 12 или выше добавьте в ваш package.json:

{
  "name": "your-project",
  "version": "1.0.0",
  "engines": {
    "node": ">=12.0.0"
  }
}

Принудительная проверка версий

Чтобы проверка версий происходила автоматически и команда завершалась с ошибкой при несовместимых версиях, необходимо включить опцию engine-strict. Это можно сделать двумя способами:

1. Создайте файл .npmrc в корне проекта

Создайте файл с именем .npmrc в той же директории, что и package.json, и добавьте:

engine-strict=true

Согласно документации npm, установка engine-strict=true заставит команды npm, такие как npm install, завершаться с ошибкой, если требуемые версии не совпадают.

2. Глобальная конфигурация (не рекомендуется для проектов)

Вы также можете установить глобально:

npm config set engine-strict true

Однако это повлияет на все операции npm глобально, что обычно не рекомендуется для требований конкретного проекта.

Синтаксические примеры

Поле engines поддерживает различные шаблоны спецификации версий с использованием семантического версионирования:

Диапазоны версий

• ">=12.0.0" – версия 12.0.0 и выше
• "^12.0.0" – совместима с версией 12.0.0 (разрешает 12.x.x, но не 13.x.x)
• "~12.0.0" – совместима с версией 12.0.0 (разрешает 12.0.x, но не 12.1.x)

Поддержка нескольких версий

Если вам нужно поддерживать несколько непоследовательных версий, можно использовать оператор ||:

{
  "engines": {
    "node": ">=12.0.0 || >=14.0.0"
  }
}

Это будет соответствовать версиям Node 12+ или 14+, но исключит версию 13.

Оба Node и npm

Можно указать требования как для Node.js, так и для npm:

{
  "engines": {
    "node": ">=12.0.0",
    "npm": ">=6.0.0"
  }
}

Альтернативные подходы

Файл .nvmrc

Для локальной разработки многие разработчики используют файл .nvmrc с менеджерами версий, такими как nvm. Создайте файл с именем .nvmrc в корне проекта:

12.0.0

Или для минимальной версии:

>=12.0.0

Когда вы переходите в каталог проекта, nvm автоматически обнаружит и переключится на указанную версию.

Проверки в CI/CD

Вы можете добавить проверки версий в ваш CI/CD pipeline:

# Пример GitHub Actions
- name: Проверка версии Node.js
  run: |
    node --version
    if ! node -e "process.exit(process.version.match(/^v(1[2-9]|[2-9][0-9])\./) ? 0 : 1)"; then
      echo "Node.js версия должна быть 12 или выше"
      exit 1
    fi

Лучшие практики

1. Будьте конкретны, но гибки: используйте >=12.0.0, а не точные версии, если только не требуется строгая совместимость.
2. Документируйте ваши требования: включите инструкции по установке в README, упомянув требования к версии Node.js.
3. Учитывайте аудиторию: если ваш проект ориентирован на новичков, будьте более снисходительны с диапазонами версий. Для специализированных инструментов можно быть строже.
4. Тщательно тестируйте: убедитесь, что ваш проект действительно работает с минимальной версией, которую вы указали.
5. Используйте CI/CD валидацию: добавьте автоматические проверки, чтобы предотвратить слияния с несовместимыми изменениями.

Согласно GeeksforGeeks, поле engines является самым простым способом указать требования к версии Node.js в package.json, что облегчает другим разработчикам понимание совместимости вашего проекта.

Источники

1. Документация npm – поле engines в package.json
2. Stack Overflow – Как указать требуемую версию Node.js в package.json?
3. GeeksforGeeks – Как определить требуемую версию Node.js в package.json?
4. DEV Community – Мой опыт с совместимостью версий Node.js
5. Marcusoft Blog – package.json: Engines & engineStrict
6. Документация pnpm – поле engines в package.json
7. DEV Community – engineStrict: true в package.json является проблематичным
8. Stack Fame – Как указать требуемую версию Node.js и npm в package.json

Заключение

Чтобы указать Node.js версии 12 или выше в вашем package.json и включить автоматическую проверку версий:

1. Добавьте поле engines в package.json: "engines": {"node": ">=12.0.0"}
2. Создайте файл .npmrc с engine-strict=true, чтобы принудительно проверять версии
3. Рассмотрите добавление файла .nvmrc для удобства локальной разработки
4. Документируйте требования в README
5. Добавьте проверки в CI/CD, чтобы предотвратить несовместимые изменения

Поле engines предоставляет стандартизированный способ сообщить пользователям о требованиях к версиям, а при включенном engine-strict оно может автоматически предотвратить установку на несовместимых версиях, помогая избежать ошибок выполнения и проблем совместимости.