Конфигурация приложения

Пакет предоставляет абстракцию "источник конфигурации" поверх переменных окружения в виде интерфейса ConfigSource и его реализаций для браузера и Node.js.

Эта абстракция может использоваться и с другими источниками данных, например с текстовыми файлами, аргументами командной строки и тд.

ConfigSource

Интерфейс ConfigSource на данный момент является alias'ом интерфейса из отличной библиотеки @humanwhocodes/env. Он содержит методы для удобной работы с переменными окружения.

Также предоставлены реализации этого интерфейса для сервера (Node.js) и браузера.

Пример использования

Допустим нам необходимо запускать http-сервер, который будет слушать порт, указанный в переменной окружения MAIN_HTTP_PORT.

Для этого используем утилиту из пакета.

import { createConfigSource } from '@sima-land/isomorph/config';

// формируем источник конфигурации
const source = createConfigSource(process.env);

// определяем порт на основе переменной из конфигурации
const port = source.require('MAIN_HTTP_PORT');

Метод require выбросит исключение если переменная не задана. Для необязательных переменных можно использовать метод get.

Подробнее в документации библиотеки @humanwhocodes/env.

Особенности реализации

Реализации в пресетах PresetWeb и PresetNode будут пытаться взять все переменные из двух источников: объекта process.env (если он существует) и объекта __ISOMORPH_ENV__ (если он существует). Для браузера эти переменные могут быть предоставлены на этапе сборки.

Важно

Реализация для сервера будет также пытаться прочитать env-файл, соответствующий окружению, определенному переменной среды NODE_ENV. Например для NODE_ENV='development' будет выполнена попытка прочитать файл .env.development

Переменные среды в браузере

В целях безопасности многие библиотеки и фреймворки не зашивают в браузерные сборки весь объект process.env целиком. Вместо этого они заменяют использование переменной среды в коде на ее значение, которое предоставлено конфигурацией сборки, например так работает webpack.DefinePlugin и webpack.EnvironmentPlugin.

Такой подход не позволяет использовать ConfigSource, так как его реализация не подразумевает прямого использования свойств в виде process.env.SOME_VAR. Вместо этого под капотом код выглядит примерно как process.env[variableName].

Для правильной работы ConfigSource в браузерных сборках, пакет isomorph предоставляет плагин EnvPlugin, который зашьёт переменные среды в специальный глобальный объект __ISOMORPH_ENV__.

const { EnvPlugin } = require('@sima-land/isomorph/utils/webpack');

module.exports = {
  target: 'web',

  // ...прочая конфигурация

  plugins: [new EnvPlugin()],
};

Важно

Плагин будет зашивать в браузерную сборку только переменные среды, имеющие префикс PUBLIC_. Также при использовании будет произведена попытка прочитать файл, соответствующий окружению. Например для NODE_ENV='development' будет выполнена попытка прочитать файл .env.development