---
title: "Environment Variables"
aliases: [env-vars, dotenv, payload-env]
tags: [payloadcms, configuration, environment, security]
sources: [raw/configuration__environment-vars.md]
created: 2026-05-15
updated: 2026-05-15
---

## Overview

Payload reads env vars from `process.env` — no Payload-specific API, just standard Node/Next.js conventions.

## Next.js Setup (default)

No extra packages needed. Add `.env` to project root:

```plaintext
project-name/
├─ .env
├─ package.json
├─ payload.config.ts
```

```plaintext
SERVER_URL=localhost:3000
DATABASE_URL=mongodb://localhost:27017/my-database
```

Use in config:

```ts
import { buildConfig } from 'payload'

export default buildConfig({
  serverURL: process.env.SERVER_URL,
  // ...
})
```

## Client-side Access (Admin Panel)

Admin Panel **does not** expose env vars to the client bundle by default.

To expose a var to client-side Custom Components, prefix with `NEXT_PUBLIC_`:

```bash
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_XXXXXXXXXXXXXXXXXX
```

```tsx
'use client'
const stripeKey = process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY
```

> **Warning:** Only expose vars that are safe for public read. Never expose secrets, DB credentials, or private API keys.

## Outside Next.js

Use [`dotenv`](https://www.npmjs.com/package/dotenv) — import as early as possible:

```ts
import dotenv from 'dotenv'
dotenv.config()

import { buildConfig } from 'payload'
// ...
```

By default `dotenv` looks for `.env` in the project root. Pass a custom path if needed:

```ts
dotenv.config({ path: '/custom/path/.env' })
```

## Key Takeaways

- Payload uses `process.env` directly — no wrapper needed
- Next.js projects: just create `.env`, no extra setup
- Non-Next.js: install `dotenv` and call `dotenv.config()` before `buildConfig`
- Client-side vars require `NEXT_PUBLIC_` prefix — and must be non-sensitive
- `.env` should always be in `.gitignore`; commit `.env.example` with placeholder values

## Related

- [[wiki/payloadcms/collection-config|Collection Config]] — where env vars feed into DB URLs, server URLs
- [[wiki/payloadcms/production|Production & Performance]] — secrets management in deployment
- [[wiki/shared-patterns/_index|Shared Patterns]] — Oliver Agency standard for `pydantic-settings` / env handling

## Sources

- `raw/configuration__environment-vars.md`
- https://payloadcms.com/docs/configuration/environment-vars
