1- # 🌐 Next.js Runtime Environment Configuration
1+ # 🌐 next-dynenv
22
33<div align =" center " >
44
77[ ![ TypeScript] ( https://img.shields.io/badge/TypeScript-ff79c6?style=for-the-badge&logo=typescript&logoColor=white )] ( https://www.typescriptlang.org/ )
88[ ![ License] ( https://img.shields.io/badge/License-MIT-f1fa8c?style=for-the-badge&logo=opensourceinitiative&logoColor=white )] ( https://opensource.org/licenses/MIT )
99
10- [ ![ npm version] ( https://img.shields.io/npm/v/@hyperb1iss/ next-runtime-env ?style=for-the-badge&logo=npm&logoColor=white&color=50fa7b )] ( https://www.npmjs.com/package/@hyperb1iss/ next-runtime-env )
10+ [ ![ npm version] ( https://img.shields.io/npm/v/next-dynenv ?style=for-the-badge&logo=npm&logoColor=white&color=50fa7b )] ( https://www.npmjs.com/package/next-dynenv )
1111[ ![ CI] ( https://img.shields.io/github/actions/workflow/status/hyperb1iss/next-runtime-env/ci.yml?branch=development&style=for-the-badge&logo=github&logoColor=white&label=CI )] ( https://github.com/hyperb1iss/next-runtime-env/actions )
12- [ ![ Downloads] ( https://img.shields.io/npm/dm/@hyperb1iss/ next-runtime-env ?style=for-the-badge&logo=npm&logoColor=white&color=ffb86c )] ( https://www.npmjs.com/package/@hyperb1iss/ next-runtime-env )
12+ [ ![ Downloads] ( https://img.shields.io/npm/dm/next-dynenv ?style=for-the-badge&logo=npm&logoColor=white&color=ffb86c )] ( https://www.npmjs.com/package/next-dynenv )
1313
1414** Effortlessly populate your environment at runtime, not just at build time.**
1515
1818
1919</div >
2020
21- > ** Fork Notice:** This package is a Next.js 15 & React 19 compatible fork of the original
22- > [ next-runtime-env] ( https://github.com/expatfile/next-runtime-env ) by Expatfile.tax LLC. All credit for the original
23- > implementation goes to the original authors.
21+ ** Dynamic runtime environment variables for Next.js.** This package is a Next.js 15/16 & React 19 compatible fork of
22+ [ next-runtime-env] ( https://github.com/expatfile/next-runtime-env ) by Expatfile.tax LLC.
2423
2524## ✨ Highlights
2625
3231- ** Secure by Default:** XSS protection via JSON escaping, immutable runtime values with ` Object.freeze `
3332- ** Zero Config:** Works out of the box with sensible defaults
3433
35- ## 🤔 Why ` next-runtime-env ` ?
34+ ## 🤔 Why ` next-dynenv ` ?
3635
3736In the modern software development landscape, the
3837[ Build once, deploy many] ( https://www.mikemcgarr.com/blog/build-once-deploy-many.html ) philosophy is key. This
3938principle, essential for easy deployment and testability, is a
4039[ cornerstone of continuous delivery] ( https://cloud.redhat.com/blog/build-once-deploy-anywhere ) and is embraced by the
4140[ twelve-factor methodology] ( https://12factor.net ) . However, front-end development, particularly with Next.js, often
42- lacks support for this - requiring separate builds for different environments. ` next-runtime-env ` bridges this gap in
43- Next.js.
41+ lacks support for this - requiring separate builds for different environments. ` next-dynenv ` bridges this gap.
4442
4543## 📦 How It Works
4644
47- ` next-runtime-env ` dynamically injects environment variables into your Next.js application at runtime. This approach
48- adheres to the "build once, deploy many" principle, allowing the same build to be used across various environments
49- without rebuilds.
45+ ` next-dynenv ` dynamically injects environment variables into your Next.js application at runtime. This approach adheres
46+ to the "build once, deploy many" principle, allowing the same build to be used across various environments without
47+ rebuilds.
5048
5149## 🔖 Version Guide
5250
53- This fork starts at version ** 4.x** to clearly differentiate from the original project:
54-
55- - ** @hyperb1iss/next-runtime-env @4.x:** Next.js 15 & React 19 with modern async server components
51+ - ** next-dynenv@4.x :** Next.js 15/16 & React 19 with modern async server components
5652
5753Original project versions (unmaintained):
5854
@@ -63,11 +59,11 @@ Original project versions (unmaintained):
6359## 📦 Installation
6460
6561``` bash
66- npm install @hyperb1iss/ next-runtime-env
62+ npm install next-dynenv
6763# or
68- pnpm add @hyperb1iss/ next-runtime-env
64+ pnpm add next-dynenv
6965# or
70- yarn add @hyperb1iss/ next-runtime-env
66+ yarn add next-dynenv
7167```
7268
7369## 🚀 Getting Started
@@ -78,7 +74,7 @@ In your root layout (`app/layout.tsx`), add the `PublicEnvScript` component:
7874
7975``` tsx
8076// app/layout.tsx
81- import { PublicEnvScript } from ' @hyperb1iss/ next-runtime-env '
77+ import { PublicEnvScript } from ' next-dynenv '
8278import type { ReactNode } from ' react'
8379
8480export default function RootLayout({ children }: { children: ReactNode }) {
@@ -105,7 +101,7 @@ guide.
105101// app/components/ClientComponent.tsx
106102' use client'
107103
108- import { env } from ' @hyperb1iss/ next-runtime-env '
104+ import { env } from ' next-dynenv '
109105
110106export default function ClientComponent() {
111107 const apiUrl = env (' NEXT_PUBLIC_API_URL' )
@@ -124,7 +120,7 @@ export default function ClientComponent() {
124120
125121``` tsx
126122// app/components/ServerComponent.tsx
127- import { env } from ' @hyperb1iss/ next-runtime-env '
123+ import { env } from ' next-dynenv '
128124
129125export default async function ServerComponent() {
130126 // Server components in Next.js 15 can be async
@@ -147,7 +143,7 @@ export default async function ServerComponent() {
147143
148144``` tsx
149145// middleware.ts
150- import { env } from ' @hyperb1iss/ next-runtime-env '
146+ import { env } from ' next-dynenv '
151147import { NextResponse } from ' next/server'
152148import type { NextRequest } from ' next/server'
153149
@@ -177,7 +173,7 @@ export const config = {
177173The ` env() ` function accepts an optional default value:
178174
179175``` tsx
180- import { env } from ' @hyperb1iss/ next-runtime-env '
176+ import { env } from ' next-dynenv '
181177
182178// Returns 'https://api.default.com' if NEXT_PUBLIC_API_URL is undefined
183179const apiUrl = env (' NEXT_PUBLIC_API_URL' , ' https://api.default.com' )
@@ -191,7 +187,7 @@ const timeout = env('NEXT_PUBLIC_TIMEOUT', '5000')
191187Use ` requireEnv() ` when a variable must be defined:
192188
193189``` tsx
194- import { requireEnv } from ' @hyperb1iss/ next-runtime-env '
190+ import { requireEnv } from ' next-dynenv '
195191
196192// Throws descriptive error if NEXT_PUBLIC_API_URL is undefined
197193const apiUrl = requireEnv (' NEXT_PUBLIC_API_URL' )
@@ -203,7 +199,7 @@ const apiUrl = requireEnv('NEXT_PUBLIC_API_URL')
203199Use ` envParsers ` to convert environment strings to typed values:
204200
205201``` tsx
206- import { envParsers } from ' @hyperb1iss/ next-runtime-env '
202+ import { envParsers } from ' next-dynenv '
207203
208204// Boolean - recognizes 'true', '1', 'yes', 'on' (case-insensitive)
209205const debug = envParsers .boolean (' NEXT_PUBLIC_DEBUG' ) // false by default
@@ -307,7 +303,7 @@ docker run -p 3000:3000 \
307303
3083041 . Add environment variables in your Vercel project settings
3093052 . Set different values for Preview, Development, and Production environments
310- 3 . Deploy your application - ` next-runtime-env ` will automatically use the runtime values
306+ 3 . Deploy your application - ` next-dynenv ` will automatically use the runtime values
311307
312308``` bash
313309vercel env add NEXT_PUBLIC_API_URL production
@@ -336,7 +332,7 @@ For static exports with runtime environment support:
336332
3373331 . Build your application: ` npm run build `
3383342 . Set environment variables on your hosting platform
339- 3 . The variables will be available at runtime through ` next-runtime-env `
335+ 3 . The variables will be available at runtime through ` next-dynenv `
340336
341337## 🔒 Security Considerations
342338
@@ -372,12 +368,12 @@ Use `requireEnv()` for required variables, or validate multiple at once:
372368
373369``` tsx
374370// Using requireEnv() - throws if undefined
375- import { requireEnv } from ' @hyperb1iss/ next-runtime-env '
371+ import { requireEnv } from ' next-dynenv '
376372
377373const apiUrl = requireEnv (' NEXT_PUBLIC_API_URL' )
378374
379375// Validating multiple variables
380- import { env } from ' @hyperb1iss/ next-runtime-env '
376+ import { env } from ' next-dynenv '
381377
382378export function validateEnv() {
383379 const required = [' NEXT_PUBLIC_API_URL' , ' NEXT_PUBLIC_APP_ID' ]
@@ -462,7 +458,7 @@ const apiUrl = env('NEXT_PUBLIC_API_URL')!
462458
463459- ** Build-time:** Variables are baked into the bundle during ` next build `
464460- ** Runtime:** Variables are injected when the application starts
465- - ` next-runtime-env ` provides runtime access, allowing the same build to work in multiple environments
461+ - ` next-dynenv ` provides runtime access, allowing the same build to work in multiple environments
466462
467463### Server vs Client Environment Access
468464
0 commit comments