Environment Variables

Define

Environment variables can be defined in .env, .env.development, and .env.production files:

# .env
 
# This environment variable is available only on the server-side
DATABASE_PASSWORD=e9wd!1hw1@#231
# This environment variable is available on both the server- and client-side
PUBLIC_ENV__CONTACT_EMAIL=hello@example.org

Only environment variables prefixed with PUBLIC_ENV__ are available on the client-side.

⚠️
PUBLIC_ENV__* environment variables must never contain secret information — all PUBLIC_ENV__* values are visible to everyone because they are included in your client bundles which are public.

# .env.development
 
# This environment variable is available only in development
DATABASE_URL=postgresql://localhost:5432

# .env.production
 
# This environment variable is available only in production
DATABASE_URL=postgresql://database.example.com:5432

You can define further .env.[mode] files.

⚠️
If your repository is public (e.g. on GitHub), then make sure your .env files never contain secret information and, instead, consider defining secrets using:

System environment variables (e.g. $ export DATABASE_PASSWORD=some-secret-password)

.env.local files (while adding *.local to your .gitignore)

Access

Use import.meta.env.SOME_ENV to access environment variables.

// /pages/movies/+data.js
// Environment: server
 
const sql = new SQL({
  // These environment variable are available here because +data runs on the server-side
  username: import.meta.env.DATABASE_URL,
  password: import.meta.env.DATABASE_PASSWORD
})
 
export async function data(pageContext) {
  const { movies } = await sql.run('SELECT * FROM movies;')
  return movies
}

// /pages/movies/+data.ts
// Environment: server
 
import type { PageContextServer } from 'vike/types'
 
const sql = new SQL({
  // These environment variable are available here because +data runs on the server-side
  username: import.meta.env.DATABASE_URL,
  password: import.meta.env.DATABASE_PASSWORD
})
 
export async function data(pageContext: PageContextServer) {
  const { movies } = await sql.run('SELECT * FROM movies;')
  return movies
}

import.meta.env.PUBLIC_ENV__* variables are also available on the client-side:

// components/ContactUs.jsx
// Environment: client
 
// This environment variable is available on the client because it's prefixed with PUBLIC_ENV__
const email = import.meta.env.PUBLIC_ENV__CONTACT_EMAIL
 
function ContactUs() {
  return <p>Contact us at {email}</p>
}

Keep in mind that import.meta.env.SOME_ENV is statically replaced:

// ✅ Works
import.meta.env.SOME_ENV
// ❌ Doesn't work
import.meta.env['SOME_ENV']
// ❌ Doesn't work
const { SOME_ENV } = import.meta.env

For server-only code, you can access environment variables using process.env, but we generally recommend import.meta.env.SOME_ENV instead because it's statically replaced for minimal bundle sizes.
// ✅ Works, eveywhere and statically replaced (minimizing bundle sizes)
import.meta.env.SOME_ENV
// ⚠️ Works, but only on server-side and no static replacement
process.env.SOME_ENV
// ⚠️ Works, but only on server-side and no static replacement
const { SOME_ENV } = process.env

TypeScript

For improved DX, consider using zod, for example:

See also: Vike's plan for built-in TypeScript support.

Static replacement

import.meta.env.SOME_ENV is statically replaced with its value at build time, enabling tree shaking (dead code elimination).

For example:

// src/someFile.js [source code in your Git repository]
 
console.log('value:', import.meta.env.DISABLE_TRACKING)
 
if (import.meta.env.DISABLE_TRACKING === 'true') {
  console.log('Tracking is disabled')
} else {
  await import('some-heavy-tracking-library')
}

# .env
 
DISABLE_TRACKING='true'

After build, src/someFile.js becomes:

// dist/server/chunks/chunk-DdwTql6x.js [built code deployed to production]
 
console.log("value:", "true");
console.log("Tracking is disabled");

The import() call is completely removed, resulting in a more lightweight production bundle.

Config files

In config files, import.meta.env isn't available (neither vite.config.js nor +config.js).

Use process.env instead.

Public allowlist

The following environment variables can be accessed from the client-side without having to prefix them with PUBLIC_ENV__:

STORYBOOK

💚
Contributions welcome to add entries to the PUBLIC_ENV_ALLOWLIST list.