npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@serggrey1992/envbridge

v0.1.1

Published

Typed runtime environment variables for Next.js and React SPAs

Downloads

477

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 есть отдельный пример и инструкция по версиям.