@t3-oss/env-nextjs: типобезопасные env для Next.js с ростом 560% в 2026

[hannadev]

В Next.js переменные окружения часто ломаются в проде - undefined значения, тайпо в ключах, отсутствие валидации. @t3-oss/env-nextjs решает это через Zod-схемы с полной типобезопасностью на этапе сборки и рантайме. Либа взлетела на 560% в 2026, потому что упрощает жизнь всем, кто работает с env.

Это не просто валидатор - это полноценный типизированный доступ к process.env без боли. Добавляешь схему один раз, и TS сразу подхватывает типы. Плюс, кикает в прод ошибку, если env невалидны. Идеально для команд, где фронт и бэк делят один .env.

Как это работает под капотом

createEnv из @t3-oss/env-nextjs генерит типизированный объект env с разделением на server и client. Server-вариаблы недоступны на клиенте - TS сразу выдаст ошибку, если попробуешь. Client требуют NEXT_PUBLIC_ префикс, иначе опять же тип-еррор. RuntimeEnv маппит process.env в схему, чтобы Next.js бандл включил все нужное.

В Next.js <13.4.4 runtimeEnv указываешь вручную, в новых версиях - experimental__runtimeEnv: process.env. Это фиксит проблемы с Edge и Client бандлами. Либа работает с Zod или Valibot, peerDeps на TS >=5.0. Версия 0.13.10 - стабильная, без сюрпризов. Установка через npm i @t3-oss/env-nextjs zod - и готово.

• Server vars: DATABASE_URL: z.string().url(), OPENAI_API_KEY: z.string().min(1) - только на сервере, throw на клиенте.
• Client vars: NEXT_PUBLIC_KEY: z.string() - доступны везде, но с префиксом.
• RuntimeEnv: ручное деструктурирование process.env.VAR - TS проверяет, все ли vars покрыты.
• В next.config.ts для standalone: добавь transpilePackages: [“@t3-oss/env-nextjs”, “@t3-oss/env-core”].

import { createEnv } from "@t3-oss/env-nextjs";
import { z } from "zod";

export const env = createEnv({
  server: {
    DATABASE_URL: z.string().url(),
  },
  client: {
    NEXT_PUBLIC_ANALYTICS_ID: z.string(),
  },
  experimental__runtimeEnv: process.env,
});

Быстрый старт в проекте

Создаешь src/env.ts, импортируешь createEnv, описываешь схемы для server/client. В .env кидаешь ключи-значения. Импортируешь env в любом api route или page, и TS автокомплитит все поля. Если забудешь var в runtimeEnv - тип-еррор на месте. В проде - рантайм-чек на валидность.

Для T3 Stack это дефолт - create-t3-app генерит boilerplate. Но либа standalone, пихай в любой Next.js. Поддержка Valibot для легковесных схем. Плюс, skipValidation опция для тестов. Всё заточено под реальные боли: deploy на Vercel с кривыми env убивает часы.

Проблема	Без @t3-oss/env-nextjs	С либой
Тайпо в ключе	Runtime undefined	TS error
Client leak secrets	Ручная проверка	Throw на клиенте
Edge bundle miss	Случайные пропуски	Авто-маппинг
Валидация	process.env?.var		fallback	Zod + types

• Добавление новой var: .env + схема в server/client + runtimeEnv.
• Пример API: const db = await connect(env.DATABASE_URL); - типы на 100%.
• Три варианта runtimeEnv: manual, experimental__, или process.env.processed.

// api/route.ts
const apiKey = env.OPENAI_API_KEY; // string, не undefined!

Сравнение с альтернативами

Обычный process.env - никакой типизации, runtime-ошибки в проде. Zod standalone - сам пишешь парсеры везде. Env-cmd или dotenv - только загрузка, без валидации. @t3-oss/env-nextjs комбинирует всё: типы, валидация, Next.js-специфика. Плюс, zero-config для T3.

Рост 560% в 2026 - от npm downloads, потому что стал дефакто-стандартом. Поддержка Next 15+, App Router, Pages Router. Интеграция с Clerk, Prisma - env.DATABASE_URL типизирован под Prisma. Минус - overhead на бандл минимальный, но для микросервисов лучше core-версия.

Либа	Типы	Next.js ready	Client/Server split	Runtime check
process.env	Нет	Частично	Нет	Нет
Zod raw	Да	Нет	Ручная	Ручная
@t3-oss/env-nextjs	Да	Да	Да	Да

• Для Vercel: env в dashboard + local .env - синхронизируется идеально.
• Тестирование: env.skipValidation = true в тестах.
• Edge Runtime: transpilePackages решает ESM/CJS проблемы.

Почему это киллер-фича для 2026

Либа эволюционировала: Valibot поддержка, auto-runtimeEnv, presets. 560% рост - команды мигрируют с кастом-решений. Осталось за кадром - интеграция с Bun/Vitest тестами env, кастом валидаторы. Подумать стоит над мульти-тенант env в монолите.

В 2026 это must-have для любого Next.js >14. Код чище, деплой safer, типы - огонь. Либа решает реальные боли без оверхеда.