Use next-safe-env in Edge Runtime and Middleware

The Edge Runtime environment used by Next.js Middleware and Vercel Edge Functions is not a full Node.js process. It runs a Web API subset and only exposes NEXT_PUBLIC_ variables at runtime - server-only secrets are never available there. next-safe-env provides a dedicated edge adapter that reflects this constraint: server vars are validated at startup but unconditionally stripped from the returned object, so your types match what is actually accessible.

Install next-safe-env

Add the package to your project.

npm install next-safe-env

Create your env config in middleware.ts

Define your schema with adapter: 'edge'. Keep the server schema empty or omit server vars - they are validated but never returned.

// middleware.ts
import { createEnv, str, url } from 'next-safe-env'

export const env = createEnv({
  server: {},  // prefer empty - server vars are validated but stripped from the result
  client: {
    NEXT_PUBLIC_API_URL:  url(),
    NEXT_PUBLIC_APP_NAME: str().default('My App'),
  },
  runtimeEnv: {
    NEXT_PUBLIC_API_URL:  process.env.NEXT_PUBLIC_API_URL,
    NEXT_PUBLIC_APP_NAME: process.env.NEXT_PUBLIC_APP_NAME,
  },
  adapter: 'edge',
})

Use env in your middleware logic

After createEnv runs, only NEXT_PUBLIC_ vars are present on the returned object. Access them directly.

// middleware.ts (continued)
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export function middleware(request: NextRequest) {
  const apiUrl = env.NEXT_PUBLIC_API_URL    // string
  const appName = env.NEXT_PUBLIC_APP_NAME  // string

  // use apiUrl or appName in your middleware logic
  return NextResponse.next()
}

Edge adapter behavior

The edge adapter applies two rules to the validation pipeline: Before validation - if your server schema contains any keys, the adapter emits a console.warn to alert you that those vars will not be accessible:

[next-safe-env] Edge adapter: server vars (API_SIGNING_KEY) will be validated
but stripped from the result - they are not accessible in Edge Runtime.

Validation still runs for those server vars. If a server var is required and missing, createEnv still fails at startup with a validation error. The warning is informational, not a skip. After validation - the adapter unconditionally strips every key that does not start with NEXT_PUBLIC_ from the returned object. This always happens, regardless of typeof window, because the Edge Runtime has no window object.

Do not put secrets in your server schema when using the edge adapter. They are validated but never returned, so accessing them on the env object at runtime will yield undefined despite passing validation. Keep your edge server schema empty, or move secrets to a separate createEnv call used only in a Node.js context.

Edge adapter vs nextjs adapter

Both adapters strip server vars from the result, but they do so under different conditions:

Adapter	When server vars are stripped
`nextjs`	Only in browser context (`typeof window !== 'undefined'`)
`edge`	Always, unconditionally

Use adapter: 'nextjs' for App Router routes and Server Components, where you need server vars to be available in the Node.js context. Use adapter: 'edge' in middleware.ts and any Vercel Edge Function, where server vars are structurally inaccessible regardless of context.

Set adapter: 'edge' explicitly rather than relying on auto-detection. The auto-detection heuristic selects edge when process is undefined or has no version, but Middleware runs in a constrained environment where the detection can be ambiguous. Being explicit makes your intent clear and avoids unexpected adapter selection.

Get Started

Guides

Concepts

Use next-safe-env in Edge Runtime and Middleware

Edge adapter behavior

Edge adapter vs nextjs adapter

​Edge adapter behavior

​Edge adapter vs nextjs adapter

Edge adapter behavior

Edge adapter vs nextjs adapter