[cloudflare] add howto env vars

pages/cloudflare/howtos/_meta.json

@@ -1,5 +1,6 @@
 {
   "NextAuth": "NextAuth",
   "stripeAPI": "Stripe API",
-  "dev": "Development workflow"
+  "dev": "Development workflow",
+  "env-vars": "Enviroment Variables"
 }

pages/cloudflare/howtos/env-vars.mdx

@@ -0,0 +1,35 @@
+## Environment variables
+
+This entry describe the most sensible way to handle your environment variables which works well both during local development and once your application is deployed to Cloudflare Workers.
+
+On the Cloudflare platform, your environment variables can be stored in either ["Enviroment variables"](https://developers.cloudflare.com/workers/configuration/environment-variables/) or ["Secrets"](https://developers.cloudflare.com/workers/configuration/secrets/). The difference being that Secrets are write only and can not be read back from either the dashboard or the CLI.
+
+### Local development
+
+While there are multiple ways to set environment variables for local development on the Cloudflare platform (adding them to to your [wrangler configuration](https://developers.cloudflare.com/workers/configuration/secrets/) or to a [.dev.vars](https://developers.cloudflare.com/workers/configuration/secrets/) file) that does not play well with the recommended development workflow as they would not be available while using `next dev`.
+
+What you should do instead is to use the Next.js [`.env` files](https://nextjs.org/docs/pages/building-your-application/configuring/environment-variables) instead. By doing so the environment variables will be available on `process.env` both while running `next dev` and when running you app locally on a Worker with `wrangler dev`.
+
+Next.js `.env` files are environment specific. That is a `.env.development` will take precedence over a `.env` file when you use the "development" environment. See the Next.js site for a detailed explanation of the [loading order](https://nextjs.org/docs/pages/building-your-application/configuring/environment-variables).
+
+You should use the `NEXTJS_ENV` environment variable to select the environment to use when running your app locally on a worker, that's how you would select the "development" environment:
+
+```plain
+# .dev.vars
+NEXTJS_ENV=development
+```
+
+The "production" environment is used by default when `NEXTJS_ENV` is not explicitely set.
+
+### Production
+
+`.env` and `dev.vars` are local files that should not be added to source control. You should instead use the cloudflare dashboard to set you environment variables for production.
+
+Next.js has [2 kinds](https://nextjs.org/docs/pages/building-your-application/configuring/environment-variables#bundling-environment-variables-for-the-browser) of environment variables:
+
+- non-`NEXT_PUBLIC_` variables which are only available on the server
+- `NEXT_PUBLIC_` variables on the other hand are available to the browser
+
+Those are called runtime environment variables (non-`NEXT_PUBLIC_`) and buildtime environment variables (`NEXT_PUBLIC_`) on the Cloudflare paltform.
+
+You can set the runtime environment variables (non-`NEXT_PUBLIC_`) by following those [instructions](https://developers.cloudflare.com/workers/configuration/environment-variables/#add-environment-variables-via-the-dashboard). The build time environment variables (`NEXT_PUBLIC_`) should be set in the [Builds Configuration](https://developers.cloudflare.com/workers/ci-cd/builds/configuration/) so that their value can be inlined by the Workers Builds.