Валідація змінних оточення в TypeScript

Схема для .env, перевірка в CI та автогенерація типів — як спіймати PORT=abc і порожній API_KEY до деплою.

Опубліковано: 25 травня 2026 р.Оновлено: 29 травня 2026 р.

Теги

Зміст

Коротко

Друкарська помилка в .env часто спливає лише на проді: PORT=abc, NODE_ENV=staging на бойовому сервері, порожній API_KEY. На Dev.to показують схему валідації та CLI env-haven — перевірка до старту застосунку й у CI.

Що сталося

Автор описує типові збої: рядок замість числа порту, хибний префікс у DATABASE_URL, відсутні обов’язкові ключі. TypeScript не рятує — process.env лишається string | undefined.

Рішення — JSON-схема змінних: тип, required, enum, формати (url, port, email), значення за замовчуванням. Файл checkmyenv.config.json у репозиторії стає єдиним джерелом правди.

Інструмент env-haven (MIT, без залежностей) валідує .env, повертає exit code 1 при помилках і вміє генерувати .env.example та env.d.ts.

Чому це важливо

Конфіг через оточення — стандарт для Node/Docker/Kubernetes, але без контракту команда покладається на пам’ять і копіпаст. Один хибний NODE_ENV може підмішати staging-ключі в production-трафік.

Проблема	Без схеми	Зі схемою
`PORT=abc`	Падіння при bind	Помилка в CI
`NODE_ENV=staging` на проді	Хибні прапорці й ключі	`enum` відхилить значення
Порожній `API_KEY`	401 від API «раптом»	«Missing required variable» до деплою

Схема + CI дешевші за нічний інцидент і розбір логів.

На практиці

Опишіть змінні в checkmyenv.config.json (тип, required, format, default).
У PR додайте крок npx env-haven — той самий .env.example, що бачить новий розробник.
Запускайте env-haven generate при зміні схеми й комітьте оновлений .env.example.
env-haven types — інтерфейс Env для обгортки над process.env після успішної перевірки.
Альтернатива в коді: Zod / Valibot при старті процесу — той самий принцип, якщо CLI не потрібен.

Для кількох середовищ копіюйте потрібний .env перед перевіркою в pipeline або тримайте окремі схеми/профілі.

Підсумок

Валідація env — малий крок із великим ефектом: перший же прогін ловить опечатки, які інакше доїжджають до моніторингу. Має сенс завести схему в будь-якому TypeScript-бэкенді, де конфіг живе в .env.