Envsafe — ваш надёжный защитник переменных окружения

Знакомая ситуация? Приложение отлично работает локально, но после деплоя в прод неожиданно падает. Причина — отсутствующая или некорректная переменная окружения. Именно такие проблемы помогает предотвратить библиотека envsafe.

Что не так с обычными переменными окружения?

Работая с process.env напрямую, мы сталкиваемся с несколькими проблемами:

Нет проверки на существование переменных
Отсутствует валидация формата значений
Невозможно задать значения по умолчанию для development
Типизация в TypeScript работает неидеально

Envsafe решает все эти проблемы, предоставляя строго типизированный и безопасный доступ к переменным окружения.

Чем хорош envsafe?

1. Строгая типизация из коробки

Библиотека написана на TypeScript и отлично работает как с TS, так и с JS-проектами. Вот как выглядит базовое использование:

import { str, envsafe, port, url } from 'envsafe';

export const env = envsafe({
  NODE_ENV: str({
    devDefault: 'development',
    choices: ['development', 'test', 'production'],
  }),
  PORT: port({
    devDefault: 3000,
  }),
  API_URL: url({
    devDefault: 'https://api.example.com',
  }),
});

2. Встроенные валидаторы

Envsafe предлагает готовые валидаторы для распространённых типов данных:

str() — строковые значения
bool() — булевы значения ("true", "false", "0", "1")
num() — числовые значения
port() — валидация портов (1-65535)
url() — проверка URL с протоколом и хостом
email() — валидация email-адресов
json() — парсинг JSON-строк

3. Гибкие настройки

Для каждого параметра можно задать:

default — значение по умолчанию
devDefault — значение только для development-окружения
choices — допустимые значения
allowEmpty — разрешение пустых строк

4. Удобное сообщение об ошибках

При ошибках envsafe выводит понятное сообщение:

========================================
❌ Invalid environment variables:
    API_URL: Invalid url input: "http//example.com/graphql"
💨 Missing environment variables:
    MY_VAR: Missing value or empty string
    PORT: Missing value or empty string
========================================

Особенности и отличия от аналогов

Envsafe вдохновлён популярной библиотекой envalid, но имеет ключевые отличия:

Полностью написан на TypeScript
Всегда строгий доступ (только к объявленным переменным)
Работает как в Node.js, так и в браузере
Нет зависимостей — минимальный размер бандла

Когда особенно полезен envsafe?

При работе в команде — явно документируете все необходимые переменные
В сложных приложениях — избегаете ошибок из-за неожиданных значений
При частых деплоях — ловите проблемы до попадания в продакшен
В fullstack-проектах — единый подход для фронтенда и бэкенда

Как начать использовать?

Установка через npm или yarn:

npm install envsafe
# или
yarn add envsafe

Пример конфигурации для Next.js приложения:

// lib/env.ts
import { envsafe, str, bool, num } from 'envsafe';

export const env = envsafe({
  NEXT_PUBLIC_API_URL: str({
    devDefault: 'http://localhost:3000/api',
  }),
  NEXT_PUBLIC_GA_ID: str({
    default: '',
    allowEmpty: true,
  }),
  ENABLE_ANALYTICS: bool({
    default: false,
  }),
});

Envsafe — это must-have инструмент для любого серьёзного проекта на Node.js или в браузере. Он:

Предотвращает ошибки в рантайме
Улучшает документацию кода
Делает работу с окружением предсказуемой
Экономит часы отладки

Особенно рекомендую попробовать envsafe, если:

Вы используете TypeScript и цените строгую типизацию
Ваше приложение работает как на сервере, так и в браузере
Вы устали от проблем с окружением в продакшене

Проект активно поддерживается, имеет хорошее покрытие тестами (судя по бейджам Code Climate) и уже используется в 800+ проектах. Отличный выбор для тех, кто ценит надёжность!