Конфигурация приложений JavaScript (Node.js): библиотеки dotenv, convict, nconf

Конфигурация приложений JavaScript (Node.js): лучшие библиотеки и практики

Любое серьёзное Node.js-приложение требует гибкой и безопасной системы конфигурации. Пароли к базам данных, API-ключи, порты серверов, уровни логирования — все эти параметры должны быть отделены от кода, легко изменяться в разных средах (разработка, тестирование, продакшн) и, самое главное, не попадать в систему контроля версий.

В этой статье мы рассмотрим три наиболее популярные библиотеки для управления конфигурацией в Node.js: dotenv, convict и nconf. Вы узнаете, как правильно настраивать приложения, избегать типичных ошибок и выбирать подходящий инструмент под свои задачи.

1. dotenv — простота и безопасность

dotenv — самая популярная библиотека для загрузки переменных окружения из файла .env. Её главное преимущество — минимализм. Вы просто создаёте файл .env, добавляете туда свои параметры, а библиотека загружает их в process.env.

Установка и базовое использование

npm install dotenv

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

PORT=3000
DB_HOST=localhost
DB_USER=admin
DB_PASS=supersecret
NODE_ENV=development

В самом начале вашего приложения (обычно в app.js или index.js) добавьте:

require('dotenv').config();

const express = require('express');
const app = express();

const port = process.env.PORT || 3000;

app.listen(port, () => {
  console.log(`Сервер запущен на порту ${port}`);
});

Важные правила работы с dotenv

• Никогда не коммитьте файл .env в Git. Добавьте его в .gitignore.
• Создайте файл .env.example с шаблоном всех переменных (без реальных значений). Это поможет новым разработчикам быстро разобраться.
• Для продакшена используйте реальные переменные окружения, установленные на сервере. dotenv нужен только для разработки.
• Не храните в .env сложные структуры данных — только строки и числа.

2. convict — валидация и схемы

Если dotenv решает задачу "как загрузить", то convict отвечает на вопрос "как проверить и структурировать". Эта библиотека позволяет задать схему конфигурации с типами данных, значениями по умолчанию и правилами валидации.

Установка и пример схемы

npm install convict

const convict = require('convict');

const config = convict({
  env: {
    doc: 'Окружение приложения',
    format: ['production', 'development', 'test'],
    default: 'development',
    env: 'NODE_ENV'
  },
  server: {
    port: {
      doc: 'Порт для HTTP-сервера',
      format: 'port',
      default: 3000,
      env: 'PORT'
    }
  },
  db: {
    host: {
      doc: 'Хост базы данных',
      format: String,
      default: 'localhost',
      env: 'DB_HOST'
    },
    password: {
      doc: 'Пароль БД',
      format: String,
      default: '',
      env: 'DB_PASS',
      sensitive: true // не выводить в логах
    }
  }
});

// Загружаем значения
config.validate({ allowed: 'strict' });

module.exports = config;

Преимущества convict

• Автоматическая валидация — если в .env будет строка вместо числа, вы получите ошибку при запуске.
• Документирование — поле doc служит встроенной документацией.
• Безопасность — помеченные sensitive: true поля не выводятся в логах.
• Поддержка вложенных структур — удобно для сложных конфигураций.

3. nconf — иерархия источников

nconf — это более мощный инструмент, который позволяет объединять настройки из нескольких источников: файлы, переменные окружения, аргументы командной строки. Приоритет источников легко настраивается.

Установка и пример использования

npm install nconf

const nconf = require('nconf');

// Определяем порядок приоритетов (сверху — самый высокий)
nconf
  .argv()           // 1. Аргументы командной строки
  .env