[Unticketed] clean up messy GA env var situation (#3025)

* Cleans up after bug introduced in https://github.com/HHS/simpler-grants-gov/pull/3001/files and fixed in #3013 * Adds some more detail to the documentation and a diagram
HHS · Dec 9, 2024 · a805bea · a805bea
1 parent 21e5c05
commit a805bea
Show file tree

Hide file tree

Showing 5 changed files with 29 additions and 6 deletions.
diff --git a/documentation/frontend/analytics.md b/documentation/frontend/analytics.md
@@ -0,0 +1,9 @@
+## Google Analytics
+
+The Next app uses the Next third party Google library to add the necessary scripts for instantiating Google Analytics (GA) on the site. To control reporting to different Google Analytics properties, we point the site at a Google Tag Manager (GTM) account ID, which manages the creation of the correct GA tags based on hostname.
+
+- When the hostname matches PROD (simpler.grants.gov), data will be reported to the production GA account
+- If the hostname matches Staging or DEV hostnames, data will be reported to the dev GA account
+- Otherwise a placeholder ID is used, and data will effectively be routed into the abyss
+
+See the "GA IDs By Hostname" variable in our GTM account for details.
diff --git a/documentation/frontend/environments.md b/documentation/frontend/environments.md
@@ -42,3 +42,21 @@ See [our CI code](https://github.com/HHS/simpler-grants-gov/blob/1b85220c7369d40
 Note that, as mentioned above, NODE_ENV will be set to "production" here due to use of `npm run build && npm start`.
 
 As a result, environment variables are gathered from the .env.production file.
+
+## Deployment
+
+[Check out this diagram](https://lucid.app/lucidchart/107dcf47-46e7-4088-a90a-1ef3b0ca3744/edit?viewport_loc=42%2C439%2C2295%2C1182%2C0_0&invitationId=inv_3559eb81-f735-4b22-9365-49920268e061). This should explain most of what the next section explains, and more but in visual form.
+
+Will add image directly to document later.
+
+### Tricky Stuff
+
+Docker and Next (and ECS) combine to create an interesting situation when trying to figure out how to provide environment variables to the deployed application. Here are a few interesting facts:
+
+- any environment variables that we want to be directly available in client code in a Next app need to be prefixed with the `NEXT_PUBLIC_` string. See [Next docs here](https://nextjs.org/docs/pages/building-your-application/configuring/environment-variables#bundling-environment-variables-for-the-browser).
+- any `NEXT_PUBLIC_` variables must be initially referenced in the code directly from process.env (`const yrVar = process.env.NEXT_PUBLIC_YR_VAR`), rather than destructured (`const { NEXT_PUBLIC_YR_VAR } = process.env`)), but can be exported from one file to another after definition
+- these variables must be available at build time (ie `next build` rather than `next start`), and can be referenced in any components when exported from a server side file, directly referenced from process.env, or passed as a prop
+- however, currently, all environment variables are passed from the ECS task definition to the application at Docker run time. This means that the `NEXT_PUBLIC_` prefix and usage as described above is not effective in our application
+- since variables defined at Docker runtime cannot be not made available directly to client components via an import or process.env reference, to make any environment variables available to client components, we will need to
+  - import the variable into a server component
+  - pass it as a prop to client component child, or implement it within a context provider
diff --git a/frontend/src/app/[locale]/layout.tsx b/frontend/src/app/[locale]/layout.tsx
@@ -84,7 +84,7 @@ export default async function LocaleLayout({ children, params }: Props) {
   return (
     <html lang={locale} suppressHydrationWarning>
       <head>
-        <GoogleAnalytics gaId={environment.NEXT_PUBLIC_GOOGLE_ANALYTICS_ID} />
+        <GoogleAnalytics gaId={environment.GOOGLE_TAG_MANAGER_ID} />
         <meta
           name="google-site-verification"
           content="jFShzxCTiLzv8gvEW4ft7fCaQkluH229-B-tJKteYJY"

diff --git a/frontend/src/constants/environments.ts b/frontend/src/constants/environments.ts
@@ -24,5 +24,5 @@ export const environment: { [key: string]: string } = {
   API_URL: API_URL || "",
   API_AUTH_TOKEN,
   NEXT_PUBLIC_BASE_URL: NEXT_PUBLIC_BASE_URL || "http://localhost:3000",
-  NEXT_PUBLIC_GOOGLE_ANALYTICS_ID: "GTM-MV57HMHS",
+  GOOGLE_TAG_MANAGER_ID: "GTM-MV57HMHS",
 };
diff --git a/infra/frontend/app-config/env-config/environment-variables.tf b/infra/frontend/app-config/env-config/environment-variables.tf
@@ -44,10 +44,6 @@ locals {
       manage_method     = "manual"
       secret_store_name = "/${var.app_name}/${var.environment}/api-auth-token"
     },
-    NEXT_PUBLIC_GOOGLE_ANALYTICS_ID = {
-      manage_method     = "manual"
-      secret_store_name = "/${var.app_name}/${var.environment}/google-analytics-id"
-    },
     NEW_RELIC_APP_NAME = {
       manage_method     = "manual"
       secret_store_name = "/${var.app_name}/${var.environment}/new-relic-app-name"