From 21488fec2ede523da06b704ca5696b4f4ae98f64 Mon Sep 17 00:00:00 2001
From: Michael Zetterberg <michael.zetterberg@scandichotels.com>
Date: Sun, 19 May 2024 20:17:53 +0200
Subject: [PATCH] docs(env): document update-dotenv.mjs

---
 update-dotenv.mjs | 45 ++++++++++++++++++++++++++++++---------------
 1 file changed, 30 insertions(+), 15 deletions(-)

diff --git a/update-dotenv.mjs b/update-dotenv.mjs
index de1fc1019..9af0975f2 100644
--- a/update-dotenv.mjs
+++ b/update-dotenv.mjs
@@ -1,19 +1,37 @@
 /**
- * We define SCANDIC_ENV_URL for stable environments on Netlify:
- * production, stage and test. Avoid using SCANDIC_ENV_URL locally.
- * For deployments to those branches we have SCANDIC_ENV_URL defined.
- * Otherwise we fallback to DEPLOY_PRIME_URL from Netlify built-in variables.
- * Locally we set DEPLOY_PRIME_URL
+ * Build time environment variables are not available in Netlify functions at
+ * runtime. The official workaround is to create an artifact and include that
+ * in the bundled functions so that the function can load/read it at runtime.
+ * In other words, during the build fill the .env file with the environment
+ * variables needed and then instruct Netlify to include the .env file together
+ * with the bundled function.
  *
- * We set NEXTAUTH_URL here because build time environment variables are not
- * available runtime in Netlify functions. This leads to use being unable to
- * login on preview deployments.
+ * This works but has two things to consider:
  *
- * This approach updates the .env file in the root of the repo and tells
- * Netlify to include this file in the bundled function output
- * (see netlify.toml). This way Next.js will read .env runtime and update the
- * environment accordingly making the value available at runtime.
+ * 1. Any environment variable created in the Netlify UI will be considered
+ *    defined. Even if the variable is set to "empty" in the Netlify UI it is
+ *    still an empty string and therefore defined.
+ *
+ * 2. Next.js uses @next/env to automatically read the .env
+ *    file into the process environment. @next/env does NOT override any
+ *    defined variables, empty strings are also considered defined. So for
+ *    @next/env to automatically pick up the .env file in the bundled functions
+ *    we need to make sure that none of the variables in the .env file are
+ *    defined in the Netlify UI. @next/env does not have any "override=true"
+ *    option, like dotenv package. So rather than introduce dotenv and manually
+ *    use it in *every* function, we can delegate to @next/env if we keep the
+ *    environment variables in Netlify UI in check.
+ *
+ * We only run this on Netlify build.
+ *
+ * We define PUBLIC_URL and use that because we are behind Akamai reverse proxy.
+ * For the stable environments (test, stage, production) these are defined. For
+ * any other environment (branch deploys and deploy previews) we use the
+ * predefined Netlify environment variable DEPLOY_PRIME_URL.
+ *
+ * NEXTAUTH_URL is set to point to the PUBLIC_URL.
  */
+
 import fs from "node:fs"
 
 if (process.env.NETLIFY) {
@@ -36,14 +54,11 @@ if (process.env.NETLIFY) {
 
   let contents = fs.readFileSync("./.env", { encoding: "utf-8" })
 
-  console.log({ pre_contents: contents })
-  console.log({ process_env: process.env })
   contents = contents.replace(/PUBLIC_URL=.*/, `PUBLIC_URL="${PUBLIC_URL}"`)
   contents = contents.replace(
     /NEXTAUTH_URL=.*/,
     `NEXTAUTH_URL="${NEXTAUTH_URL}"`
   )
-  console.log({ post_contents: contents })
 
   fs.writeFileSync("./.env", contents, { encoding: "utf-8" })
 }