feat: retrieve CLI environment variables from process.env and .env* files (#937)

Co-authored-by: James Anderson <[email protected]>

Author: vicb

.changeset/quiet-snails-hope.md

@@ -0,0 +1,15 @@
+---
+"@opennextjs/cloudflare": minor
+---
+
+feat: retrieve CLI environment variables from `process.env` and `.env*` files
+
+Recommended usage on CI:
+
+- Add your secrets to `process.env` (i.e. `CF_ACCOUNT_ID`)
+- Add public values to the wrangler config `wrangler.jsonc` (i.e. `R2_CACHE_PREFIX_ENV_NAME`)
+
+Recommended usage for local dev:
+
+- Add your secrets to either a `.dev.vars*` or `.env*` file (i.e. `CF_ACCOUNT_ID`)
+- Add public values to the wrangler config `wrangler.jsonc` (i.e. `R2_CACHE_PREFIX_ENV_NAME`)

packages/cloudflare/src/api/cloudflare-context.ts

@@ -340,6 +340,10 @@ async function getCloudflareContextFromWrangler<
 
 	const { env, cf, ctx } = await getPlatformProxy({
 		...options,
+		// The `env` passed to the fetch handler does not contain variables from `.env*` files.
+		// because we invoke wrangler with `CLOUDFLARE_LOAD_DEV_VARS_FROM_DOT_ENV`=`"false"`.
+		// Initializing `envFiles` with an empty list is the equivalent for this API call.
+		envFiles: [],
 		environment,
 	});
 	return {

packages/cloudflare/src/cli/build/utils/extract-project-env-vars.ts

@@ -6,7 +6,7 @@ import type { BuildOptions } from "@opennextjs/aws/build/helper.js";
 
 function readEnvFile(filePath: string) {
 	if (fs.existsSync(filePath) && fs.statSync(filePath).isFile()) {
-		return parse(fs.readFileSync(filePath).toString());
+		return parse(fs.readFileSync(filePath, "utf-8"));
 	}
 }
 

packages/cloudflare/src/cli/commands/deploy.ts

@@ -23,27 +23,30 @@ export async function deployCommand(args: WithWranglerArgs<{ cacheChunkSize?: nu
 	printHeaders("deploy");
 
 	const { config } = await retrieveCompiledConfig();
-	const options = getNormalizedOptions(config);
+	const buildOpts = getNormalizedOptions(config);
 
 	const wranglerConfig = readWranglerConfig(args);
 
-	const envVars = await getEnvFromPlatformProxy({
-		configPath: args.wranglerConfigPath,
-		environment: args.env,
-	});
+	const envVars = await getEnvFromPlatformProxy(config, buildOpts);
 
-	const deploymentMapping = await getDeploymentMapping(options, config, envVars);
+	await populateCache(
+		buildOpts,
+		config,
+		wranglerConfig,
+		{
+			target: "remote",
+			environment: args.env,
+			wranglerConfigPath: args.wranglerConfigPath,
+			cacheChunkSize: args.cacheChunkSize,
+			shouldUsePreviewId: false,
+		},
+		envVars
+	);
 
-	await populateCache(options, config, wranglerConfig, {
-		target: "remote",
-		environment: args.env,
-		wranglerConfigPath: args.wranglerConfigPath,
-		cacheChunkSize: args.cacheChunkSize,
-		shouldUsePreviewId: false,
-	});
+	const deploymentMapping = await getDeploymentMapping(buildOpts, config, envVars);
 
 	runWrangler(
-		options,
+		buildOpts,
 		[
 			"deploy",
 			...args.wranglerArgs,

packages/cloudflare/src/cli/commands/helpers.ts

@@ -1,23 +1,75 @@
+import { type BuildOptions } from "@opennextjs/aws/build/helper.js";
 import { getPlatformProxy, type GetPlatformProxyOptions } from "wrangler";
 
+import { extractProjectEnvVars } from "../build/utils/extract-project-env-vars.js";
+
 export type WorkerEnvVar = Record<keyof CloudflareEnv, string | undefined>;
 
 /**
- * Return the string env vars from the worker.
+ * Returns the env vars to use by the CLI.
+ *
+ * The environments variables are returned from a combination of `process.env`, wrangler config, and `.env*` files.
+ *
+ * Recommended usage on CI:
+ *
+ * - Add you secrets to `process.env` (i.e. `CF_ACCOUNT_ID`)
+ * - Add public values to the wrangler config `wrangler.jsonc` (i.e. `R2_CACHE_PREFIX_ENV_NAME`)
+ *
+ * Note: `.dev.vars*` and `.env*` should not be checked in.
+ *
+ * Recommended usage for local dev:
+ *
+ * - Add you secrets to either a `.dev.vars*` or `.env*` file (i.e. `CF_ACCOUNT_ID`)
+ * - Add public values to the wrangler config `wrangler.jsonc` (i.e. `R2_CACHE_PREFIX_ENV_NAME`)
+ *
+ * Note: `.env*` files are also used by `next dev` while `.dev.var*` files are only loaded by `wrangler`.
+ *
+ * Loading details:
+ *
+ * 1. The variables are first initialized from `process.env`
+ * 2. They are then augmented/replaced with variables from the wrangler config (`wrangler.jsonc` and `.dev.vars*`)
+ * 3. They are then augmented with variables from `.env*` files (existing values are not replaced).
  *
  * @param options Options to pass to `getPlatformProxy`, i.e. to set the environment
+ * @param buildOpts Open Next build options
  * @returns the env vars
  */
-export async function getEnvFromPlatformProxy(options: GetPlatformProxyOptions) {
-	const envVars = {} as WorkerEnvVar;
-	const proxy = await getPlatformProxy<CloudflareEnv>(options);
+export async function getEnvFromPlatformProxy(options: GetPlatformProxyOptions, buildOpts: BuildOptions) {
+	// 1. Start from `process.env`
+	const envVars = process.env;
+
+	// 2. Apply vars from workers `env`
+	const proxy = await getPlatformProxy<CloudflareEnv>({
+		...options,
+		// Next.js uses a different mechanism to load `.env*` files from wrangler.
+		// We prevent wrangler for loading the files and handle that in `getEnvFromPlatformProxy`.
+		envFiles: [],
+	});
+
 	Object.entries(proxy.env).forEach(([key, value]) => {
 		if (typeof value === "string") {
+			// filter out bindings by only considering string values
 			envVars[key as keyof CloudflareEnv] = value;
 		}
 	});
+
 	await proxy.dispose();
-	return envVars;
+
+	// 3. Apply new vars from `.env*` files
+	let mode: "production" | "development" | "test" = "production";
+	if (envVars.NEXTJS_ENV === "development") {
+		mode = "development";
+	} else if (envVars.NEXTJS_ENV === "test") {
+		mode = "test";
+	}
+
+	const dotEnvVars = extractProjectEnvVars(mode, buildOpts);
+
+	for (const varName in dotEnvVars) {
+		envVars[varName] ??= dotEnvVars[varName];
+	}
+
+	return envVars as unknown as WorkerEnvVar;
 }
 
 /**