✨ Add serverOnly() for safe isomorphic access to server secrets

Introduce a new function that reads server-only environment variables
without throwing in browser contexts. Unlike env(), serverOnly():

- Returns the fallback value when called from client code
- Never throws errors, enabling safe use in shared modules
- Supports lazy evaluation patterns with Zod schemas

This enables cleaner isomorphic code where server secrets can be
referenced in shared configuration without conditional imports.

Includes comprehensive tests covering both browser and server contexts
using module re-importing to properly test the IS_BROWSER detection.

Author: hyperb1iss

README.md

@@ -194,6 +194,42 @@ const apiUrl = requireEnv('NEXT_PUBLIC_API_URL')
 // Error: "Required environment variable 'NEXT_PUBLIC_API_URL' is not defined."
 ```
 
+### Server-Only Variables
+
+Use `serverOnly()` for non-public environment variables in code that runs on both client and server. Unlike `env()`,
+this function **never throws** in the browser—it gracefully returns the fallback value:
+
+```tsx
+import { serverOnly } from 'next-dynenv'
+
+// Returns the actual value on server, fallback on client
+const dbUrl = serverOnly('DATABASE_URL', 'postgresql://localhost:5432/dev')
+const apiSecret = serverOnly('API_SECRET_KEY') // undefined on client
+```
+
+This is particularly useful for shared configuration modules with lazy evaluation:
+
+```tsx
+import { env, serverOnly } from 'next-dynenv'
+import { z } from 'zod'
+
+const configSchema = z.object({
+    supabaseUrl: z.string().url(),
+    supabaseAnonKey: z.string(),
+    // Server-only: returns undefined on client, real value on server
+    supabaseServiceKey: z.string().optional(),
+})
+
+// Safe to import anywhere—evaluates lazily
+export const config = lazy(() =>
+    configSchema.parse({
+        supabaseUrl: env('NEXT_PUBLIC_SUPABASE_URL'),
+        supabaseAnonKey: env('NEXT_PUBLIC_SUPABASE_ANON_KEY'),
+        supabaseServiceKey: serverOnly('SUPABASE_SERVICE_KEY'),
+    }),
+)
+```
+
 ### Type-Safe Parsers
 
 Use `envParsers` to convert environment strings to typed values:

package.json

@@ -74,5 +74,6 @@
     "peerDependencies": {
         "next": "^15 || ^16",
         "react": "^19"
-    }
+    },
+    "packageManager": "pnpm@10.25.0+sha512.5e82639027af37cf832061bcc6d639c219634488e0f2baebe785028a793de7b525ffcd3f7ff574f5e9860654e098fe852ba8ac5dd5cefe1767d23a020a92f501"
 }

src/script/env.spec.ts

@@ -1,5 +1,5 @@
-import { afterEach, describe, expect, it } from 'vitest'
-import { env, requireEnv } from './env'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { env, requireEnv, serverOnly } from './env'
 
 declare global {
     var mockWindow: (envVars: Record<string, string>) => void
@@ -89,3 +89,79 @@ describe('requireEnv()', () => {
         )
     })
 })
+
+describe('serverOnly()', () => {
+    afterEach(() => {
+        delete process.env.SECRET_KEY
+        delete process.env.DATABASE_URL
+    })
+
+    // In jsdom, window always exists, so IS_BROWSER is true
+    // These tests verify browser behavior (returns fallback)
+
+    it('should return fallback in browser context', () => {
+        // window exists in jsdom, so this simulates browser
+        expect(serverOnly('SECRET_KEY', 'fallback-value')).toEqual('fallback-value')
+    })
+
+    it('should return undefined when no fallback provided in browser', () => {
+        expect(serverOnly('SECRET_KEY')).toBeUndefined()
+    })
+
+    it('should not read process.env in browser context', () => {
+        process.env.SECRET_KEY = 'actual-secret'
+        // Even though the env var exists, browser should return fallback
+        expect(serverOnly('SECRET_KEY', 'fallback')).toEqual('fallback')
+    })
+
+    // Test server behavior by re-importing module without window
+    describe('server context', () => {
+        it('should return process.env value on server', async () => {
+            // Save original window
+            const originalWindow = globalThis.window
+
+            // Remove window to simulate server
+            // @ts-expect-error - intentionally removing window
+            delete globalThis.window
+
+            // Reset module cache and re-import
+            vi.resetModules()
+            const { serverOnly: serverOnlyServer } = await import('./env')
+
+            process.env.SECRET_KEY = 'server-secret'
+            expect(serverOnlyServer('SECRET_KEY')).toEqual('server-secret')
+
+            // Restore window
+            globalThis.window = originalWindow
+            vi.resetModules()
+        })
+
+        it('should return fallback when env var undefined on server', async () => {
+            const originalWindow = globalThis.window
+            // @ts-expect-error - intentionally removing window
+            delete globalThis.window
+
+            vi.resetModules()
+            const { serverOnly: serverOnlyServer } = await import('./env')
+
+            expect(serverOnlyServer('NONEXISTENT_VAR', 'default')).toEqual('default')
+
+            globalThis.window = originalWindow
+            vi.resetModules()
+        })
+
+        it('should return undefined when no fallback and env var undefined on server', async () => {
+            const originalWindow = globalThis.window
+            // @ts-expect-error - intentionally removing window
+            delete globalThis.window
+
+            vi.resetModules()
+            const { serverOnly: serverOnlyServer } = await import('./env')
+
+            expect(serverOnlyServer('NONEXISTENT_VAR')).toBeUndefined()
+
+            globalThis.window = originalWindow
+            vi.resetModules()
+        })
+    })
+})

src/script/env.ts

@@ -1,6 +1,8 @@
-import { isBrowser } from '../helpers/is-browser'
+import { isBrowser as isBrowserWithEnv } from '../helpers/is-browser'
 import { PUBLIC_ENV_KEY } from './constants'
 
+const IS_BROWSER = typeof window !== 'undefined'
+
 /**
  * Reads environment variables safely from both browser and server contexts.
  *
@@ -64,7 +66,7 @@ import { PUBLIC_ENV_KEY } from './constants'
 export function env(key: string): string | undefined
 export function env<T extends string>(key: string, defaultValue: T): string
 export function env(key: string, defaultValue?: string): string | undefined {
-    if (isBrowser()) {
+    if (isBrowserWithEnv()) {
         if (!key.startsWith('NEXT_PUBLIC_')) {
             throw new Error(
                 `Environment variable '${key}' is not public and cannot be accessed in the browser.\n` +
@@ -125,3 +127,73 @@ export function requireEnv(key: string): string {
     }
     return value
 }
+
+/**
+ * Safely reads a server-only environment variable.
+ *
+ * Returns the fallback value when running in the browser, allowing this function
+ * to be safely called from code that runs on both client and server (e.g., shared
+ * lazy getters, utility modules).
+ *
+ * Unlike {@link env}, this function:
+ * - **Never throws** in the browser—it gracefully returns the fallback
+ * - Is designed for **non-`NEXT_PUBLIC_*`** variables that shouldn't be exposed to clients
+ * - Provides a clean pattern for isomorphic code that needs server secrets
+ *
+ * @param key - The environment variable name to retrieve
+ * @param fallback - Optional fallback value returned in the browser or if undefined
+ * @returns The environment variable value on the server, or the fallback on the client/if undefined
+ *
+ * @example
+ * Basic usage with server-only secrets:
+ * ```ts
+ * import { serverOnly } from 'next-dynenv'
+ *
+ * // Returns the actual value on server, undefined on client
+ * const dbUrl = serverOnly('DATABASE_URL')
+ *
+ * // With a fallback for development
+ * const apiKey = serverOnly('API_SECRET_KEY', 'dev-key')
+ * ```
+ *
+ * @example
+ * In shared code with lazy evaluation (e.g., with Zod schemas):
+ * ```ts
+ * import { env, serverOnly } from 'next-dynenv'
+ * import { z } from 'zod'
+ *
+ * const configSchema = z.object({
+ *   supabaseUrl: z.string().url(),
+ *   supabaseAnonKey: z.string(),
+ *   // Server-only: returns fallback on client, real value on server
+ *   supabaseServiceKey: z.string().optional(),
+ * })
+ *
+ * // This lazy getter can be safely imported anywhere
+ * const config = lazy(() => configSchema.parse({
+ *   supabaseUrl: env('NEXT_PUBLIC_SUPABASE_URL'),
+ *   supabaseAnonKey: env('NEXT_PUBLIC_SUPABASE_ANON_KEY'),
+ *   supabaseServiceKey: serverOnly('SUPABASE_SERVICE_KEY'),
+ * }))
+ * ```
+ *
+ * @example
+ * Conditional server-side logic:
+ * ```ts
+ * import { serverOnly } from 'next-dynenv'
+ *
+ * // Safe to call anywhere—returns undefined on client
+ * const internalUrl = serverOnly('INTERNAL_SERVICE_URL') || publicUrl
+ * ```
+ *
+ * @see {@link env} for public variables accessible on both client and server
+ * @see {@link requireEnv} for required variables that throw if undefined
+ */
+export function serverOnly(key: string): string | undefined
+export function serverOnly<T extends string>(key: string, fallback: T): string
+export function serverOnly(key: string, fallback?: string): string | undefined {
+    if (IS_BROWSER) {
+        return fallback
+    }
+    return process.env[key] ?? fallback
+}

src/script/index.ts

@@ -1,7 +1,7 @@
 /* istanbul ignore file */
 
 export { PUBLIC_ENV_KEY } from './constants'
-export { env, requireEnv } from './env'
+export { env, requireEnv, serverOnly } from './env'
 export { EnvScript } from './env-script'
 export { envParsers } from './parsers'
 export { PublicEnvScript } from './public-env-script'