[Docs] Clarify how to access environment variables vs bindings

[thomasgauvin]

The bindings docs explain that you can obtain the Cloudflare env using getCloudflareContext from "@opennextjs/cloudflare". In the Cloudflare Workers world, this would return both the bindings and the environment variables.

However, it seems that the documentation on environment variables indicates that environment variables will be accessible on process.env, and in my experience, they will specifically not be available on the Cloudflare context (even if they are set in Wrangler.jsonc, etc). Does OpenNext inject environment variables from Wrangler.jsonc and Workers environment variables into process.env? Or does it only accept environment variables configured via the dashboard? If so, this should be explicitly mentioned in either bindings or Environment variables docs.

[celestial-rose]

Especially since Wrangler is now injecting .env into process.env, somehow the builds get injected with some .env variables and don’t need them in wrangler.jsonc nor in the dashboard (?)

[Juuldamen]

From my experience if you add values to the Wrangler config these will be available through getCloudflareContext on the server-side. If you use process.env directly you need the nodejs_compat flag of at least 2025-04-01 and a Wrangler version that supports this version when running locally, try npm ls workerd to see the last supported flag for your Wrangler version. Otherwise, flags before this date do not have it enabled by default, which I found out the hard way.

https://developers.cloudflare.com/changelog/2025-03-11-process-env-support/

Then with Next.js you also have the NEXT_PUBLIC prefixed env vars which are added to the bundle at compile time. It might be that the next build does not pick these up from the Wrangler config. Maybe you already tried this, more of a FYI ;-)

Personally I have a next-on-pages project set up with the below, I assume it works the same with OpenNext:

• .env.development.local: loaded when running next dev with it's default NODE_ENV=development.
• .env.production.local: loaded when running next build with it's default NODE_ENV=production.
• wrangler.json vars: loaded when running wrangler dev preview. Where compile time vars are already in the bundle through the Next.js build. Only issue here is that you don't want secrets in your wrangler.json. Still need to find something for this.

Where .env.production.local is a file automatically generated before building by parsing the wrangler.json config and mapping the vars key from there. So I don't have to manage environment variables for builds in multiple files. If you find a nicer setup, feel free to let me know. Would be helpful if there was a best practice setup in the docs/starter app template.

[leonardo2204]

@Juuldamen Hi, can you better elaborate the .env.production.local generation? I'm having this same problem now, I can see that the npm run build is picking .env.local, thus screwing up everything.

Thanks

[vicb]

@thomasgauvin

The bindings docs explain that you can obtain the Cloudflare env using getCloudflareContext from "@opennextjs/cloudflare". In the Cloudflare Workers world, this would return both the bindings and the environment variables.

"this would return both the bindings and the environment variables" unfortunately cloudflare uses the same "environment variables" term that Node.js for something different.

The "(cloudflare) environment variables" available on env are the same as what you are used to when using Workers.

Node.js app developpers use process.env to access the "(system) environment variable". That's what you want to do when writing a Next app.

However, it seems that the documentation on environment variables indicates that environment variables will be accessible on process.env

Yes, the doc is right

in my experience, they will specifically not be available on the Cloudflare context (even if they are set in Wrangler.jsonc, etc).

They are, for 2 reasons:

• OpenNext takes cares of this
• Workerd in nodejs_compat mode after 04/01/2025 copy the env on process.env.

This is poorly documented :(

I feel like all of your questions are answered in the docs or do you see anything specific to add (PR welcome)