@serggrey1992/envbridge
v0.1.1
Published
Typed runtime environment variables for Next.js and React SPAs
Downloads
477
Maintainers
Readme
EnvBridge
Типизированные runtime environment variables для Next.js App Router и обычного React SPA. Одна сборка приложения запускается с разными переменными окружения. Без Provider, Context, hooks, схем значений, преобразований и defaults. Все getters возвращают string | undefined.
Подключение рассчитано на Next.js 13.5.11+, 14.2.35+, 15.5.28+ и 16.2.9+, App Router, React 18/19. Требуется Node.js >=22.18 независимо от минимальных требований самого Next.js. Точные проверенные сочетания и результаты — в матрице совместимости. Next.js 13.0–13.4 и Pages Router не входят в поддержку.
npm-пакет: @serggrey1992/envbridge · CLI: envbridge · репозиторий
Выберите подключение
| Приложение | Что подключать | Инструкция | |---|---|---| | Next.js 13–16 App Router | Node Route Handler + RuntimeEnvScript | Next.js и .env по версиям | | React SPA (проверено Vite, React18/19) | classic runtime-env.js до module entry | Обычный React |
Для React SPA Next.js устанавливать не требуется. Конфиг, generate и client getters общие. Команда bootstrap отдельно создаёт JS с публичными runtime-значениями; на Next.js её роль выполняет RuntimeEnvScript.
Установка и конфигурация
Установка: npm install @serggrey1992/envbridge. Для локальной проверки используйте tarball из npm pack.
// runtime.config.ts
import { defineRuntimeConfig } from '@serggrey1992/envbridge/config';
export default defineRuntimeConfig({
output: './runtime-env', // необязательно, это значение по умолчанию
envFiles: ['.env', '.env.development', '.env.test', '.env.staging', '.env.production'],
public: ['API_URL', 'AUTH_URL', 'APP_NAME'],
server: ['JWT_SECRET', 'DATABASE_URL'],
});По умолчанию envFiles: ['.env']. Имена определяются только массивами public/server. Дубликаты внутри списка или между списками запрещены. NEXT_PUBLIC_* допустимы; библиотека читает их по динамическому ключу, без build-time подстановки. Опубликованные ключи доступны любому посетителю независимо от префикса.
npx envbridge generate
# либо npm exec envbridge -- generate
# либо pnpm exec envbridge generateГенерируются только runtime-env/client.ts, runtime-env/server.ts и выбранные .env-файлы. Значений в TypeScript нет. Измените output, например, на ./src/shared/config/runtime-env; все пути считаются от корня проекта.
// runtime-env/client.ts — создаётся автоматически
// AUTO-GENERATED BY @serggrey1992/envbridge
// DO NOT EDIT MANUALLY
import { getPublicEnv } from '@serggrey1992/envbridge/client';
export const env = {
get API_URL(): string | undefined { return getPublicEnv('API_URL'); },
// остальные public getters генерируются аналогично
};// runtime-env/server.ts — создаётся автоматически
// AUTO-GENERATED BY @serggrey1992/envbridge
// DO NOT EDIT MANUALLY
import 'server-only';
import { getServerEnv } from '@serggrey1992/envbridge/server';
export const env = {
get JWT_SECRET(): string | undefined { return getServerEnv('JWT_SECRET'); },
// остальные server getters генерируются аналогично
};Обязательная интеграция Next.js
Ниже подключение для Next.js 13–16 без Cache Components. Для cacheComponents: true используйте готовый пример. Обёртка next.config не требуется.
Начиная с версии 0.1.1 используются понятные адреса
/runtime-envи/runtime-env/bootstrap. При обновлении с 0.1.0 перенесите обработчик; переход описан в migration.md.
// app/runtime-env/route.ts
import { createRuntimeEnvHandler } from '@serggrey1992/envbridge/next';
import runtimeConfig from '../../runtime.config';
export const runtime = 'nodejs';
export const dynamic = 'force-dynamic';
export const GET = createRuntimeEnvHandler(runtimeConfig);
export const HEAD = GET;При структуре src/app разместите обработчик в src/app/runtime-env/route.ts и скорректируйте путь импорта конфига.
// app/layout.tsx — Server Component
import { RuntimeEnvScript } from '@serggrey1992/envbridge/next';
import runtimeConfig from '../runtime.config';
export const dynamic = 'force-dynamic';
export default function Layout({ children }: { children: React.ReactNode }) {
return <html><head><RuntimeEnvScript config={runtimeConfig} /></head><body>{children}</body></html>;
}force-dynamic поддерживается всеми целевыми версиями. На Next.js 15/16 можно вместо него использовать await connection() до рендера env-компонентов, но для единого подключения это не требуется.
Обычный Next config нужен лишь для собственных настроек приложения, например:
// next.config.mjs — совместим с Next.js 13–16
/** @type {import('next').NextConfig} */
export default { output: 'standalone' };Если вы уже используете createRuntimeEnvProxy на Next.js 16, его можно оставить: API сохранён. Обновите config.matcher в proxy.ts на ['/runtime-env', '/__runtime-env'], чтобы он пропускал новый адрес и старые браузерные bundles. Новый Route Handler заменяет proxy.ts, создавать одновременно оба endpoint не нужно. Не переносите старый proxy в Edge middleware Next.js 13/14: для гарантированного runtime-чтения используйте Node Route Handler. Endpoint должен обходить middleware авторизации, редиректы и кеш CDN.
При CSP передайте nonce: <RuntimeEnvScript config={runtimeConfig} nonce={nonce} />. Разрешите nonce в script-src, а 'self' в connect-src.
Использование
'use client';
import { env } from '@/runtime-env/client'; // настройте alias под свой output
export function AppName() { return <div>{env.APP_NAME}</div>; }// Server Component — этот же public модуль можно использовать при SSR
import { env as publicEnv } from '@/runtime-env/client';
import { env as serverEnv } from '@/runtime-env/server';
export default function Page() {
// секрет использовать только на сервере, не возвращать в JSX/props/Response
const secret = serverEnv.JWT_SECRET;
return <p>{publicEnv.APP_NAME}: {secret ? 'configured' : 'not configured'}</p>;
}Дополнительные getters приложения необязательны:
import { env } from '@/runtime-env/client';
export const variables = { get API() { return env.API_URL; } };clientEnv.JWT_SECRET, clientEnv.UNKNOWN и serverEnv.API_URL вызывают TypeScript error. Импорт server entrypoint из Client Component вызывает реальную ошибку Next build через server-only. Дополнительно предусмотрена проверка браузерного исполнения.
SSR, hydration и ошибки
На сервере public getter читает process.env[key] при каждом обращении. В браузере он читает снимок текущего документа, созданный bootstrap до hydration. Не меняйте process.env во время работы процесса: согласованность отдельных запросов при такой мутации не гарантируется.
RuntimeEnvScript должен находиться в head динамического root layout, до hydration. Для одинакового подключения на Next.js 13–16 задайте export const dynamic = 'force-dynamic' в root layout. На Next.js 15/16 альтернативой служит await connection() до рендера использующих env компонентов. Ленивый getter сам не переводит страницу в динамический режим.
global-error.tsx заменяет root layout. При прямой ошибке root layout скрипт может отсутствовать. Поэтому первое браузерное чтение при отсутствии снимка один раз делает синхронный XHR к /runtime-env, получает только public allowlist и сохраняет снимок. Последующие чтения и переходы сетевых запросов не требуют. Существующий снимок сохраняется при клиентском переходе на error boundary.
Это явный компромисс синхронного API: XHR блокирует основной поток и deprecated в браузерах. Некоторые политики браузера и Permissions Policy могут его запрещать; в этом случае выбрасывается диагностическая ошибка. Поддержка отключённого sync XHR не заявлена. Без layout bootstrap не вызывайте getter в обработчиках unload/pagehide.
- Инициализированная отсутствующая переменная →
undefined. - Инициализированное пустое значение →
''. - Снимка нет и XHR API недоступен →
RuntimeEnvNotInitializedError. - Сетевая ошибка, неверный JSON/status или CSP блокировка →
RuntimeEnvBootstrapError; ошибка запоминается до reload.
Не подавляйте диагностические ошибки преобразованием в undefined. Endpoint возвращает no-store для браузера и CDN. Не добавляйте service worker/CDN кеширование. При смене окружения нужен полный reload документа.
Порядок .env одинаков на всех поддерживаемых ветках Next.js: process.env → .env.<NODE_ENV>.local → .env.local (кроме test) → .env.<NODE_ENV> → .env. KEY= в приоритетном файле перекрывает непустое значение из общего .env. Dev использует development, build/start — production. Не требуется заполнять все файлы; подробности и корректный standalone запуск — в руководстве Next.js.
Проверяемые сценарии: обычный SSR, streaming, прямые/клиентские 404, notFound(), segment error, root/global error, reload ошибки, Retry и возврат к обычной странице. Детали — результаты проверок.
CLI и безопасность файлов
envbridge generate --env production
envbridge generate --env development,staging
envbridge generate --env default # выбирает .env
envbridge generate --env-only
envbridge generate --code-only
envbridge generate --cwd ./apps/web
envbridge generate --cwd ./apps/web --config ./configs/runtime.config.ts
envbridge generate --help--config считается от --cwd, по умолчанию cwd процесса. Output и envFiles всегда относительно --cwd, даже если конфиг в configs/. --env выбирает исключительно файлы из envFiles. Также принимает полное имя .env.production. --env-only и --code-only несовместимы.
За пределы корня запись запрещена. Явное исключение для output — --allow-outside-root. Symlink и hardlink целевые файлы всё равно запрещены. Конфиг — доверенный исполняемый код Node.js; не запускайте чужой runtime.config.ts.
Существующий dotenv только дополняется отсутствующими ключами в конце. Сохраняются комментарии, значения, кавычки, export, BOM, CRLF/LF и неизвестные переменные. Повторная генерация не меняет ни байты, ни mtime. Multiline quoted значения разбираются целиком. Неоднозначный синтаксис, дубликаты или незакрытые кавычки останавливают генерацию с номером строки без вывода значений.
Все назначения проверяются до записи. Generated TypeScript перезаписывается только при точном заголовке библиотеки. Новые файлы и замена generated модулей устанавливаются атомарно из временных файлов в той же директории; существующий dotenv дополняется через append. При обычной ошибке записи выполненные изменения откатываются. Это не многофайловая транзакция при отключении питания/kill; не запускайте параллельные генераторы и не меняйте пути во время запуска. Нет гарантии против процесса, одновременно злонамеренно меняющего родительские директории.
Генератор предупреждает о Git при наличии server ключей; .gitignore автоматически не изменяется. Сами исключите .env* (кроме безопасного example). Включение secret в public делает его публичным: библиотека не определяет смысл имён. Не передавайте секреты в React props, HTML, API ответы или клиентские логи.
Docker и CI/CD
Полный пример — examples/next-app, развёртывание.
npm ci
npx envbridge generate --code-only
npm run build
# одна сборка, разные запуски
APP_NAME=Development API_URL=https://dev.example.com node .next/standalone/server.js
APP_NAME=Production API_URL=https://api.example.com node .next/standalone/server.jsПередавайте значения средствами окружения контейнера (docker run --env-file ...), Kubernetes или CI. .env.test — стандартное имя Next.js. .env.staging и .env.testing Next.js автоматически не загружает. CLI создаёт их как шаблоны, но загрузить значения должен способ развёртывания, например docker run --env-file .env.staging image. Не кладите секретные env-файлы в Docker image.
Проверки разработки
npm ci
npm run check
npm run prepare:example
npm run test:consumer
npx playwright install chromium
npm run test:e2e
npm run test:react
npm run test:compat
npm run test:static
npm run test:example-dev
npm run test:docker
npm packДля уже установленного Chromium можно задать PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH. Тесты используют порты 3191–3197. Docker-проверка требует работающий Docker engine. test:e2e собирает положительный consumer один раз и запускает его с двумя окружениями в обычном и standalone режимах. Отдельная отрицательная сборка подтверждает запрет server-only в Client Component. test:compat повторяет этот цикл в независимых consumers с разными Next.js/React; можно выбрать одну строку через NRE_NEXT_VERSION=13.5.11 npm run test:compat. CI ничего не публикует и не создаёт release.
Ограничения и troubleshooting
- MVP: Node runtime, App Router, корневой endpoint;
basePath, multi-zones, Edge, static export, экспериментальный PPR Next 14/15, Pages Router и версии Next.js вне указанной матрицы не поддерживаются. - Статически сгенерированный HTML с env содержит build-time значения. Ни getters, ни endpoint не исправляют уже созданный HTML. Переведите страницы в динамический режим; не помещайте runtime-чтение в
use cache. - Hydration mismatch: проверьте force-dynamic в layout и endpoint, положение bootstrap, совпадение окружений backend instances, отсутствие HTML кеша и мутаций process.env.
- Bootstrap failed: проверьте
/runtime-env(200 JSON), Route Handler вapp/runtime-env/route.ts, исключение из middleware, CSP, auth redirect, CDN и доступность sync XHR. - Пустая строка вместо undefined: generated
.envсодержитKEY=, это существующее пустое значение. Удалите строку, если переменная действительно должна отсутствовать. - После смены окружения старые значения: выполните полный reload и уберите кеширование HTML/endpoint.
- Ошибка перезаписи generated TS: выберите другой output или вручную перенесите свой файл; CLI не удаляет пользовательские файлы.
Переход с прежнего имени пакета: миграция в EnvBridge.
Для Next.js 16 с cacheComponents и partialPrefetching есть отдельный пример и инструкция по версиям.
