Environment Variables

There are two categories of configuration to think about:

• Environment variables: API keys, feature flags, config strings, etc.
• Worker bindings: Cloudflare resources such as D1, KV, R2 or Durable Objects.

The distinction matters because the way you access each is different.

Environment variables

Using .env files ensures that environment variables are available on process.env both when running next dev and when running your app locally on a Worker with wrangler dev.

You can follow typical Next.js conventions where you have either a single .env file, or environment specific files such as .env.development.

.env

When you run next dev, these are automatically loaded and can be accessed with process.env. When previewing your app under Workers (with npm run preview), you'll still use .env* for most values.

API_BASE_URL=http://localhost:3000
NEXT_PUBLIC_ANALYTICS_KEY=dev-123

.dev.vars

You can use the NEXTJS_ENV environment variable to select which environment to use when running your app locally on a Worker. To use the development environment, create a .dev.vars file:

NEXTJS_ENV=development

Production builds

Cloudflare does not see your local .env files. When deploying to production, you must configure your environment variables and secrets separately.

Deploying via CLI

When deploying via the CLI using npm run deploy, Wrangler will use the variables and secrets you have previously configured via Wrangler commands (see Adding secrets below).

Your .env files remain local and are never uploaded to Cloudflare. Before your first deployment, ensure you have set all required secrets and variables using Wrangler commands.

Deploying via Cloudflare Builds

If you are using Cloudflare Builds for automatic deployments, you must set variables and secrets in two places:

1. Build configuration: Set build-time variables and secrets in your build configuration. The Worker needs access to inline any NEXT_PUBLIC_* variables, and access to non-NEXT_PUBLIC_* variables needed for statically generated pages.

2. Runtime configuration: Additionally set runtime variables and secrets on your Worker (see Production runtime below).

Production runtime

If you need to access variables at runtime, you must additionally add them to your Worker's Variables and Secrets configuration (a separate configuration to the ones used in a the build configuration).

Adding secrets

Secrets are encrypted, and once set cannot be read back again. The main way to set Secrets is via Wrangler:

npx wrangler secret put KEY [options]

• KEY (required). The variable name for this secret to be accessed in the Worker.
• --env (optional). Perform on a specific environment, e.g. --production

After running this command, you will be prompted to input the actual value. Paste it into the terminal:

⛅️ wrangler 4.28.0
─────────────────────────────────────────────
? Enter a secret value: » ****

Wrangler will then confirm success:

⛅️ wrangler 4.28.0
─────────────────────────────────────────────
√ Enter a secret value: ... ****
🌀 Creating the secret for the Worker "next-cloudflare-turbo" 
✨ Success! Uploaded secret TEST_SECRET

Worker bindings

Bindings are treated differently to environment variables. Bindings represent Cloudflare resources such as the D1 database, R2 buckets etc.

The OpenNext adapter provides a getCloudflareContext() function for exactly this:

import { createDrizzleD1 } from "@nct/db"
import { getCloudflareContext } from "@opennextjs/cloudflare"

export const getDb = cache(() => {
  const { env } = getCloudflareContext() 
  return createDrizzleD1(env.DB) 
})

Examples

Client-side public variable (NEXT_PUBLIC_*)

Let's walk through adding a public analytics key that needs to be available on the client side.

NEXT_PUBLIC_ANALYTICS_KEY=dev-analytics-123

"use client"

export function Analytics() {
  const analyticsKey = process.env.NEXT_PUBLIC_ANALYTICS_KEY
  
  // Your analytics implementation
  return <script data-key={analyticsKey} />
}

npx wrangler secret put NEXT_PUBLIC_ANALYTICS_KEY

? Enter a secret value: » prod-analytics-789

npm run deploy

Build-time variable (SSG)

Let's walk through adding a CMS API key that's needed to fetch content during static site generation.

CMS_API_KEY=dev-cms-key-123

import { notFound } from "next/navigation"

async function getPost(slug: string) {
  const response = await fetch(`https://cms.example.com/posts/${slug}`, {
    headers: {
      'Authorization': `Bearer ${process.env.CMS_API_KEY}`
    }
  })
  
  if (!response.ok) return null
  return response.json()
}

export async function generateStaticParams() {
  const response = await fetch('https://cms.example.com/posts', {
    headers: {
      'Authorization': `Bearer ${process.env.CMS_API_KEY}`
    }
  })
  
  const posts = await response.json()
  return posts.map((post) => ({ slug: post.slug }))
}

export default async function BlogPost({ params }: { params: { slug: string } }) {
  const post = await getPost(params.slug)
  
  if (!post) notFound()
  
  return (
    <article>
      <h1>{post.title}</h1>
      <div>{post.content}</div>
    </article>
  )
}

CMS_API_KEY=prod-cms-key-789

npm run deploy

Summary

FAQs