Skip to main content

Documentation Index

Fetch the complete documentation index at: https://next-safe-env.dev/llms.txt

Use this file to discover all available pages before exploring further.

next-safe-env works in Vite projects through its vite adapter, which enforces the VITE_ prefix on all client schema keys and reads client variables from import.meta.env instead of process.env. You get the same typed, validated env object you would in a Next.js app - the adapter handles the differences in how Vite exposes variables to the browser bundle.

​
Create your env file

1

Install next-safe-env

npm install next-safe-env
2

Create src/env.ts

Define your server and client schemas. All client keys must be prefixed with VITE_. In runtimeEnv, use import.meta.env for client variables and process.env for server variables.
// src/env.ts
import { createEnv, str, url, port, bool } from 'next-safe-env'

export const env = createEnv({
  server: {
    DATABASE_URL: url(),
    PORT:         port().default(3000),
  },
  client: {
    VITE_API_URL:   url(),
    VITE_APP_NAME:  str().default('My App'),
    VITE_DEBUG:     bool().default(false),
  },
  runtimeEnv: {
    DATABASE_URL:  process.env.DATABASE_URL,
    PORT:          process.env.PORT,
    VITE_API_URL:  import.meta.env.VITE_API_URL,
    VITE_APP_NAME: import.meta.env.VITE_APP_NAME,
    VITE_DEBUG:    import.meta.env.VITE_DEBUG,
  },
  adapter: 'vite',
})
3

Import env anywhere in your app

import { env } from './env'

env.DATABASE_URL   // string  (server-only)
env.PORT           // number  (server-only)
env.VITE_API_URL   // string
env.VITE_APP_NAME  // string
env.VITE_DEBUG     // boolean

​
VITE_ prefix enforcement

The vite adapter checks every key in your client schema before validation runs. If any key does not start with VITE_, the adapter throws immediately: 
Error: [next-safe-env] Client env var "API_URL" must be prefixed with VITE_.
Vite only exposes variables with the VITE_ prefix to the browser bundle. Any client variable without the prefix would be silently undefined at runtime - next-safe-env turns that silent failure into a loud startup error.

​
Auto-detection

If you omit adapter: 'vite' but any of your client schema keys start with VITE_, next-safe-env detects this and selects the vite adapter automatically. You will see a console warning prompting you to set the adapter explicitly: 
[next-safe-env] Detected VITE_ client keys - using vite adapter. Set adapter: 'vite' explicitly to suppress this warning.
Add adapter: 'vite' to your config to suppress the warning and make the intent clear.
Use import.meta.env.VITE_* in runtimeEnv for client variables and process.env.* for server variables. Vite statically replaces import.meta.env.VITE_* references at build time, which is how it keeps those values out of the server bundle and vice versa.