From b48be218402f8a7e73091340f12708add0aaff17 Mon Sep 17 00:00:00 2001
From: An-Ting Hsu <12019694+andyhsu10@users.noreply.github.com>
Date: Wed, 10 Jun 2026 17:13:25 +0800
Subject: [PATCH] feat: optional Google Analytics 4 via @next/third-parties

GA loads only when NEXT_PUBLIC_GA_ID is set, so local dev and PR previews
stay untracked. Production reads it from a GitHub Actions repo variable.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .env.example                 |  4 ++++
 .github/workflows/deploy.yml |  2 ++
 app/layout.tsx               |  6 ++++++
 package.json                 |  1 +
 pnpm-lock.yaml               | 20 ++++++++++++++++++++
 5 files changed, 33 insertions(+)
 create mode 100644 .env.example

diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..2ed03cc
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,4 @@
+# Google Analytics 4 Measurement ID. Leave empty to disable GA.
+# Local dev: copy this file to `.env.local` and fill in your ID.
+# Production: set as a GitHub Actions repository variable named NEXT_PUBLIC_GA_ID.
+NEXT_PUBLIC_GA_ID=
diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
index 7d20438..1c2a076 100644
--- a/.github/workflows/deploy.yml
+++ b/.github/workflows/deploy.yml
@@ -41,6 +41,8 @@ jobs:
           cache: pnpm
       - run: pnpm install --frozen-lockfile
       - run: pnpm build
+        env:
+          NEXT_PUBLIC_GA_ID: ${{ vars.NEXT_PUBLIC_GA_ID }}
       - uses: actions/upload-pages-artifact@v3
         with:
           path: out
diff --git a/app/layout.tsx b/app/layout.tsx
index a68bd4a..7845e70 100644
--- a/app/layout.tsx
+++ b/app/layout.tsx
@@ -1,7 +1,12 @@
 import type { Metadata } from "next";
 import { Inter, JetBrains_Mono } from "next/font/google";
+import { GoogleAnalytics } from "@next/third-parties/google";
 import "./globals.css";
 
+// Set NEXT_PUBLIC_GA_ID (e.g. "G-XXXXXXXXXX") to enable Google Analytics.
+// When unset (local dev, PR previews), GA is not loaded.
+const gaId = process.env.NEXT_PUBLIC_GA_ID;
+
 const inter = Inter({ subsets: ["latin"], variable: "--font-inter" });
 const jetbrains = JetBrains_Mono({ subsets: ["latin"], variable: "--font-jetbrains" });
 
@@ -28,6 +33,7 @@ export default function RootLayout({ children }: { children: React.ReactNode })
         <script dangerouslySetInnerHTML={{ __html: noFlash }} />
       </head>
       <body className="font-sans antialiased">{children}</body>
+      {gaId ? <GoogleAnalytics gaId={gaId} /> : null}
     </html>
   );
 }
diff --git a/package.json b/package.json
index 5fc7909..5aadc53 100644
--- a/package.json
+++ b/package.json
@@ -17,6 +17,7 @@
   "author": "An-Ting Hsu",
   "license": "MIT",
   "dependencies": {
+    "@next/third-parties": "15",
     "next": "15",
     "react": "19",
     "react-dom": "19"
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index fd150b8..310d158 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -8,6 +8,9 @@ importers:
 
   .:
     dependencies:
+      '@next/third-parties':
+        specifier: '15'
+        version: 15.5.19(next@15.5.19(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(react@19.2.7)
       next:
         specifier: '15'
         version: 15.5.19(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
@@ -444,6 +447,12 @@ packages:
     cpu: [x64]
     os: [win32]
 
+  '@next/third-parties@15.5.19':
+    resolution: {integrity: sha512-vJXvZOZKDRY9mWoMrFpiB8OAXtTc7tlEu4ig8/kkaKszNO/oXQmdGpywxwnSPJqxS6SlZPZZDgOFSFBCoo3rag==}
+    peerDependencies:
+      next: ^13.0.0 || ^14.0.0 || ^15.0.0
+      react: ^18.2.0 || 19.0.0-rc-de68d2f4-20241204 || ^19.0.0
+
   '@nodelib/fs.scandir@2.1.5':
     resolution: {integrity: sha512-vq24Bq3ym5HEQm2NKCr3yXDwjc7vTsEThRDnkp2DK9p1uqLR+DHurm/NOTo0KG7HYHU7eppKZj3MyqYuMBf62g==}
     engines: {node: '>= 8'}
@@ -2216,6 +2225,9 @@ packages:
     resolution: {integrity: sha512-uxc/zpqFg6x7C8vOE7lh6Lbda8eEL9zmVm/PLeTPBRhh1xCgdWaQ+J1CUieGpIfm2HdtsUpRv+HshiasBMcc6A==}
     engines: {node: '>=6'}
 
+  third-party-capital@1.0.20:
+    resolution: {integrity: sha512-oB7yIimd8SuGptespDAZnNkzIz+NWaJCu2RMsbs4Wmp9zSDUM8Nhi3s2OOcqYuv3mN4hitXc8DVx+LyUmbUDiA==}
+
   tinybench@2.9.0:
     resolution: {integrity: sha512-0+DUvqWMValLmha6lr4kD8iAMK1HzV0/aKnCtWb9v9641TnP/MFb7Pc2bxoxQjTXAErryXVgUOfv2YqNllqGeg==}
 
@@ -2747,6 +2759,12 @@ snapshots:
   '@next/swc-win32-x64-msvc@15.5.19':
     optional: true
 
+  '@next/third-parties@15.5.19(next@15.5.19(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(react@19.2.7)':
+    dependencies:
+      next: 15.5.19(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      react: 19.2.7
+      third-party-capital: 1.0.20
+
   '@nodelib/fs.scandir@2.1.5':
     dependencies:
       '@nodelib/fs.stat': 2.0.5
@@ -4631,6 +4649,8 @@ snapshots:
 
   tapable@2.3.3: {}
 
+  third-party-capital@1.0.20: {}
+
   tinybench@2.9.0: {}
 
   tinyexec@1.2.4: {}