TypeScript types exported by next-safe-env

next-safe-env exports a set of TypeScript types you can use to annotate functions, derive types from your schema, or build wrapper utilities. All types are re-exported from the package root, so you can import them directly from next-safe-env. None of these types have a runtime representation - they exist solely in the TypeScript type system.

`ServerOnly<T>`

ServerOnly<T> brands a type T with a unique symbol that marks it as originating from the server schema. Every value in the returned env object that comes from a server key carries this brand, making its origin visible in IDE tooltips.

declare const SERVER_ONLY_BRAND: unique symbol

type ServerOnly<T> = T & { readonly [SERVER_ONLY_BRAND]: void }

Because TypeScript uses structural typing, ServerOnly<T> is assignment-compatible with T. It does not produce a compile error by itself. To get a hard compile error when client components import server vars, add import 'server-only' at the top of your env.ts file.

import type { ServerOnly } from 'next-safe-env'

// Annotate a function that only accepts server-side values
function connectDB(url: ServerOnly<string>) { /* ... */ }

`ClientEnv<TEnv>`

ClientEnv<TEnv> strips every ServerOnly-branded key from an env type, leaving only the client-safe keys. Use it to constrain functions or components that must not access server variables.

type ClientEnv<TEnv extends Record<string, unknown>> = {
  [K in keyof TEnv as TEnv[K] extends { readonly [SERVER_ONLY_BRAND]: void }
    ? never
    : K]: TEnv[K]
}

import type { ClientEnv } from 'next-safe-env'
import { env } from '@/env'

type ClientVars = ClientEnv<typeof env>

// TypeScript errors if you reference a server key here
function renderHeader(vars: ClientVars) {
  return vars.NEXT_PUBLIC_APP_NAME  // ✅ fine
  // vars.DATABASE_URL              // ✗ property does not exist on ClientVars
}

`InferEnv<TServer, TClient>`

InferEnv<TServer, TClient> is the full return type of createEnv(). Server keys are wrapped in ServerOnly<T>; client keys are their plain inferred types. The whole object is Readonly.

type InferEnv<
  TServer extends Schema | ZodObjectLike<Record<string, unknown>>,
  TClient extends Schema | ZodObjectLike<Record<string, unknown>>,
> = Readonly<
  { [K in keyof InferInput<TServer>]: ServerOnly<InferInput<TServer>[K]> } &
    InferInput<TClient>
>

You rarely need to reference InferEnv directly - the return type of createEnv() is inferred automatically. Use it when you need to pass the env type as a generic argument elsewhere.

import type { InferEnv } from 'next-safe-env'

type MyEnv = InferEnv<typeof serverSchema, typeof clientSchema>

`InferSchema<T>`

InferSchema<T> maps a Schema (a Record<string, FieldValidator<unknown>>) to the object type its validators produce. It reads the phantom _type property from each FieldValidator to extract the output type.

type InferSchema<T extends Schema> = {
  [K in keyof T]: T[K] extends FieldValidator<infer V> ? V : never
}

import type { InferSchema } from 'next-safe-env'
import { str, url, port } from 'next-safe-env'

const serverSchema = {
  DATABASE_URL: url(),
  PORT:         port().default(3000),
  NODE_ENV:     str().enum(['development', 'production', 'test']),
}

type ServerShape = InferSchema<typeof serverSchema>
// { DATABASE_URL: string; PORT: number; NODE_ENV: 'development' | 'production' | 'test' }

`InferInput<T>`

InferInput<T> infers the output type from either a native Schema or a ZodObjectLike. For Zod schemas it reads the _output phantom property; for native schemas it delegates to InferSchema<T>.

type InferInput<T> = T extends ZodObjectLike<
  infer O extends Record<string, unknown>
>
  ? O
  : T extends Schema
    ? InferSchema<T>
    : never

This type is used internally by InferEnv to handle both native and Zod schemas uniformly.

`EnvConfig<TServer, TClient>`

EnvConfig<TServer, TClient> is the shape of the config object passed to createEnv(). Refer to the createEnv() reference for a full description of each field.

type EnvConfig<
  TServer extends Schema | ZodObjectLike<Record<string, unknown>>,
  TClient extends Schema | ZodObjectLike<Record<string, unknown>>,
> = {
  server: TServer
  client: TClient
  runtimeEnv: {
    [K in (
      | (TServer extends ZodObjectLike<infer O extends Record<string, unknown>>
          ? keyof O
          : keyof TServer)
      | (TClient extends ZodObjectLike<infer O extends Record<string, unknown>>
          ? keyof O
          : keyof TClient)
    ) &
      string]?: string | undefined
  }
  adapter?: 'nextjs' | 'node' | 'edge' | 'vite'
  skipValidation?: boolean
  onValidationError?: (error: ValidationErrorShape) => never
}

`ValidationFailure`

ValidationFailure describes a single failed field produced during validation. An array of these is attached to EnvValidationError and passed to onValidationError.

type ValidationFailure = {
  field: string
  expected: string
  received: string
  message: string
}

string

required

The environment variable name that failed, e.g. "DATABASE_URL".

string

required

A human-readable description of what was expected, e.g. "valid URL" or "length >= 32".

string

required

The actual value (or "undefined") that was received.

string

required

The full error message combining expected and received, e.g. "Expected valid URL. Got: \"postgres-localhost\"".

`ValidationStats`

ValidationStats provides a summary count of how many variables were checked and how many failed, split by server and client. It is attached to EnvValidationError.

type ValidationStats = {
  serverTotal: number
  clientTotal: number
  serverFailed: number
  clientFailed: number
}

number

required

Total number of keys in the server schema.

number

required

Total number of keys in the client schema.

number

required

Number of server keys that failed validation.

number

required

Number of client keys that failed validation.

`FieldValidator<T>`

FieldValidator<T> is the interface every validator class implements. The generic T is the TypeScript output type - string, number, boolean, or their | undefined variants. The _type property is a phantom: it never exists at runtime and is only used by InferSchema<T> to extract T.

interface FieldValidator<T = unknown> {
  readonly isOptional: boolean
  readonly defaultValue: T | undefined
  // phantom - satisfies the interface but never assigned at runtime (use `declare`)
  _type: T
  parse(rawValue: unknown, fieldName: string): T
}

boolean

required

true when .optional() has been called on the validator.

T | undefined

required

The fallback value set by .default(v), or undefined if no default was configured.

(rawValue: unknown, fieldName: string) => T

required

Parses and validates rawValue. Throws a FieldError if the value is invalid. Called once per field during the validation pass inside createEnv().

`Adapter`

Adapter is the interface that all built-in adapters (nextjs, node, edge, vite) implement. You can also implement this interface to build a custom adapter.

type Adapter = {
  name: string
  beforeValidate(
    serverSchema: Schema,
    clientSchema: Schema,
    rawEnv: Record<string, string | undefined>,
  ): Record<string, string | undefined>
  afterValidate<T extends Record<string, unknown>>(env: T): T
}

string

required

Identifier for the adapter, e.g. "nextjs" or "node".

function

required

Called before any field is validated. Receives the server schema, client schema, and raw env map. Can throw to block startup (e.g., when a NEXT_PUBLIC_ prefix is missing). Returns the raw env map - possibly filtered - that validation runs against.

function

required

Called after all fields pass validation. Receives the fully-validated env object and returns it, optionally with keys stripped (e.g., the edge adapter removes all non-NEXT_PUBLIC_ keys unconditionally).

Zod interop types

These types are exported for advanced Zod interop use cases. They are duck-typed interfaces - no zod package import is required.

`ZodTypeLike<T>`

A duck-typed interface matching zod.ZodType. createEnv() detects Zod schemas at runtime using this structural shape.

interface ZodTypeLike<T = unknown> {
  readonly _output: T
  safeParse(
    data: unknown,
  ): { success: true; data: T } | { success: false; error: ZodErrorLike }
}

`ZodObjectLike<T>`

A duck-typed interface matching zod.ZodObject. Required for the createEnv({ server: z.object({ ... }) }) syntax.

interface ZodObjectLike<
  T extends Record<string, unknown> = Record<string, unknown>,
> extends ZodTypeLike<T> {
  readonly shape: Record<string, ZodTypeLike<unknown>>
}

`ZodErrorLike`

A duck-typed interface matching the error shape exposed by zod.ZodError.

type ZodErrorLike = {
  readonly errors: ReadonlyArray<{
    readonly path: ReadonlyArray<string | number>
    readonly message: string
  }>
}

​ServerOnly<T>

​ClientEnv<TEnv>

​InferEnv<TServer, TClient>

​InferSchema<T>

​InferInput<T>

​EnvConfig<TServer, TClient>

​ValidationFailure

​ValidationStats

​FieldValidator<T>

​Adapter

​Zod interop types

​ZodTypeLike<T>

​ZodObjectLike<T>

​ZodErrorLike

`ServerOnly<T>`

`ClientEnv<TEnv>`

`InferEnv<TServer, TClient>`

`InferSchema<T>`

`InferInput<T>`

`EnvConfig<TServer, TClient>`

`ValidationFailure`

`ValidationStats`

`FieldValidator<T>`

`Adapter`

Zod interop types

`ZodTypeLike<T>`

`ZodObjectLike<T>`

`ZodErrorLike`