@tramvai/module-environment

Env

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

Подключение

Уже поставляется внутри @tramvai/module-common и не нужно устанавливать, если подключен module-common.

Иначе, нужно установить @tramvai/module-environment

Explanation

Динамически генерируемый список используемых ENV переменных

Все используемые параметры в приложения регистрируются с помощью реализации в DI токена ENV_USED_TOKEN и предполагается, что каждый модуль по отдельности регистрирует только те ENV параметры, которые ему необходимы. В таком случае при подключении модуля, будет автоматическая валидация всех переданных параметров, которые необходимы для работы приложения

import { provide } from '@tramvai/core';

@Module({
  providers: [
    provide({
      provide: ENV_USED_TOKEN,
      useValue: [
        { key: 'DEBUG_MODULE', optional: true },
        { key: 'DEBUG_MODULE_URL', optional: true },
      ],
      multi: true,
    }),
  ],
})
export class MyModule {}

В выше примере, модуль регистрирует несколько env токенов, которые будут проинициализированы и будут доступны в environmentManager.get('DEBUG_MODULE'). При этом, был передан параметр optional который указывает, что переменные не обязательные для работы приложения.

Валидация переданных параметров

При старте приложения происходит проверка тех токенов, которые были зарегистрированы в DI и были переданы в ENV при запуске. Если в приложение не были переданы все требуемые ENV переменные, то приложение упадет.

Так-же есть возможность написать валидаторы для ENV значений, которые запустятся при инициализации приложения.

import { provide } from '@tramvai/core';

@Module({
  providers: [
    provide({
      provide: ENV_USED_TOKEN,
      useValue: [
        {
          key: 'MY_ENV',
          validator: (env) => {
            if (!env.includes('https')) {
              return 'Не правильный формат ссылки. Ссылка должна содержать https';
            }
          },
        },
      ],
      multi: true,
    }),
  ],
})
export class MyModule {}

Функциональность работает на сервере и в браузере

Все ENV переменные будут доступны как на сервере, так и браузере без каких либо дополнительных действий и настроек. В браузер автоматически передаются env переменные, которые имеют dehydrate: true

Приоритет получения значений для env переменных

Так-как есть возможность перезаписывать значения переменных, то переменные заменятся по определенным правилам

Правила замены, расположены в порядке приоритета, от меньшего к высокому:

• Параметры заданные в токенах { key: 'ENV_PARAM', value: 'env value' }
• Параметры записанные в файле env.development.js
• Передача параметров запуска приложения MY_ENV=j node server.js

API

Экспортируемые токены и TS интерфейс

@inline ../../tokens/common/src/env.ts

How to

Как прочитать данные в приложении

Допустим мы зарегистрировали используемый ENV параметр CONFIG_API с помощью токена ENV_USED_TOKEN, теперь в приложении нужно подключить environmentManager и прочитать данные

import { provide } from '@tramvai/core';

@Module({
  providers: [
    provide({
      provide: 'MY_SERVICE',
      useClass: class MyService {
        constructor({ environmentManager }) {
          console.log(environmentManager.get('CONFIG_API'));
        }
      },
      deps: {
        environmentManager: ENV_MANAGER_TOKEN,
      },
    }),
  ],
})
export class MyModule {}

Этот код будет работать как на сервере, так и в браузере

Как можно просто передать параметры при локальной разработке

Для этого создайте файл env.development.js в корне проекта и пропишите все ENV переменные для приложения. При инициализации приложения, будет прочитан этот файл.

Особенности использования env.developmen.js в production сборке

Приложение двенадцати факторов хранит конфигурацию в переменных окружения, поэтому по умолчанию при process.env.NODE_ENV === 'production' EnvironmentManger не будет считывать файл env.development.js.

Если же необходимо локально протестировать приложение с NODE_ENV=production, можно передать флаг DANGEROUS_UNSAFE_ENV_FILES='true' чтобы EnvironmentManger прочитал файл env.development.js и не пришлось вводить все переменные руками.

Как при деплоях передать ENV параметры приложению

Для этого при запуске приложения передайте ENV параметры. Например в Docker можно это сделать через параметр -e docker run -e MY_ENV_VAR=/ my-image