fix: prevent duplicate scripts on soft navigation (#29)

vklimontovich · vklimontovich · commit 28de5c112a75 · 2026-02-10T18:33:24.000-05:00
Introduce script `mode` property to control execution timing:
- "once": run only on first mount (gtag.js, analytics init)
- "on-params-change": run when template params change (config with user_id)
- "every-render": run on every navigation (page_view events)

Refactor client.tsx to use React components with proper lifecycle management
instead of imperative DOM manipulation.

Add e2e test for script mode behavior during soft navigation.
diff --git a/e2e/test-app/src/app/page.tsx b/e2e/test-app/src/app/page.tsx
@@ -1,4 +1,5 @@
 import { auth } from "@/auth";
+import Link from "next/link";
 
 export default async function Home() {
   const session = await auth();
@@ -23,9 +24,9 @@ export default async function Home() {
         </div>
       )}
       <nav>
-        <a href="/test-page" data-testid="test-page-link">
+        <Link href="/test-page" data-testid="test-page-link">
           Test Page
-        </a>
+        </Link>
       </nav>
     </main>
   );
diff --git a/e2e/test-app/src/app/test-page/page.tsx b/e2e/test-app/src/app/test-page/page.tsx
@@ -1,8 +1,15 @@
+import Link from "next/link";
+
 export default function TestPage() {
   return (
     <main>
       <h1>App Router Test Page</h1>
       <p data-testid="page-marker">This is a test page for App Router</p>
+      <nav>
+        <Link href="/" data-testid="home-link">
+          Back to Home
+        </Link>
+      </nav>
     </main>
   );
 }
diff --git a/e2e/test-app/src/nextlytics.ts b/e2e/test-app/src/nextlytics.ts
@@ -1,12 +1,83 @@
 import { Nextlytics } from "@nextlytics/core/server";
 import { postgrestBackend } from "@nextlytics/core/backends/postgrest";
+import type { NextlyticsBackend } from "@nextlytics/core";
 import { auth } from "./auth";
 
+// Inline types for test backend (avoid import issues with workspace)
+type ScriptMode = "once" | "on-params-change" | "every-render";
+type ScriptElement = { async?: boolean; body?: string; src?: string; mode?: ScriptMode };
+type JavascriptTemplate = { items: ScriptElement[] };
+type ClientAction = { items: Array<{ type: "script-template"; templateId: string; params: unknown }> };
+
+const CONSOLE_TEMPLATE_ID = "console-test";
+
+/**
+ * Test backend that injects console.log scripts with different modes.
+ * Used to verify script injection behavior during soft navigation.
+ */
+function consoleTestBackend(): NextlyticsBackend {
+  return {
+    name: "console-test",
+    returnsClientActions: true,
+
+    getClientSideTemplates(): Record<string, JavascriptTemplate> {
+      return {
+        [CONSOLE_TEMPLATE_ID]: {
+          items: [
+            // mode: "once" - should only run once, even after soft navigation
+            {
+              body: [
+                "window.__nextlyticsTestOnce = (window.__nextlyticsTestOnce || 0) + 1;",
+                "console.log('[nextlytics-test] once:', window.__nextlyticsTestOnce);",
+              ].join("\n"),
+              mode: "once",
+            },
+            // mode: "on-params-change" - should run when params change
+            {
+              body: [
+                "window.__nextlyticsTestParamsChange = (window.__nextlyticsTestParamsChange || 0) + 1;",
+                "console.log('[nextlytics-test] on-params-change:', window.__nextlyticsTestParamsChange, 'path={{path}}');",
+              ].join("\n"),
+              mode: "on-params-change",
+            },
+            // mode: "every-render" (default) - should run on every navigation
+            {
+              body: [
+                "window.__nextlyticsTestEveryRender = (window.__nextlyticsTestEveryRender || 0) + 1;",
+                "console.log('[nextlytics-test] every-render:', window.__nextlyticsTestEveryRender);",
+              ].join("\n"),
+            },
+          ],
+        },
+      };
+    },
+
+    async onEvent(event): Promise<ClientAction> {
+      // Return script insertion for pageView events
+      if (event.type === "pageView") {
+        return {
+          items: [
+            {
+              type: "script-template",
+              templateId: CONSOLE_TEMPLATE_ID,
+              params: { path: event.serverContext?.path || "/" },
+            },
+          ],
+        };
+      }
+      return { items: [] };
+    },
+
+    updateEvent() {},
+  };
+}
+
 const backends = [
   postgrestBackend({
     url: process.env.POSTGREST_URL || "http://localhost:3001",
     tableName: "analytics",
   }),
+  consoleTestBackend(),
 ];
 
 export const { middleware, handlers, analytics } = Nextlytics({
diff --git a/e2e/test-app/src/pages/pages-home.tsx b/e2e/test-app/src/pages/pages-home.tsx
@@ -1,4 +1,5 @@
 import { useSession } from "next-auth/react";
+import Link from "next/link";
 
 export default function PagesHome() {
   const { data: session } = useSession();
@@ -23,9 +24,9 @@ export default function PagesHome() {
         </div>
       )}
       <nav>
-        <a href="/pages-test" data-testid="test-page-link">
+        <Link href="/pages-test" data-testid="test-page-link">
           Test Page
-        </a>
+        </Link>
       </nav>
     </main>
   );
diff --git a/e2e/test-app/src/pages/pages-test.tsx b/e2e/test-app/src/pages/pages-test.tsx
@@ -1,8 +1,15 @@
+import Link from "next/link";
+
 export default function PagesTestPage() {
   return (
     <main>
       <h1>Pages Router Test Page</h1>
       <p data-testid="page-marker">This is a test page for Pages Router</p>
+      <nav>
+        <Link href="/pages-home" data-testid="home-link">
+          Back to Home
+        </Link>
+      </nav>
     </main>
   );
 }
diff --git a/e2e/test-app/tsconfig.json b/e2e/test-app/tsconfig.json
@@ -11,7 +11,7 @@
     "moduleResolution": "bundler",
     "resolveJsonModule": true,
     "isolatedModules": true,
-    "jsx": "react-jsx",
+    "jsx": "preserve",
     "incremental": true,
     "plugins": [
       {
diff --git a/e2e/tests/analytics.test.ts b/e2e/tests/analytics.test.ts
@@ -139,5 +139,85 @@ describe.each(versions)("%s", (version) => {
 
       await page.close();
     });
+
+    it("script modes work correctly during soft navigation", async () => {
+      // This test only applies to App Router (soft navigation with <Link>)
+      if (routerType !== "app") return;
+
+      const page = await testApp.newPage();
+
+      // Visit home page
+      await testApp.visitHome(page);
+      await page.waitForLoadState("networkidle");
+
+      // Wait for initial scripts to execute
+      await page.waitForFunction(() => window.__nextlyticsTestOnce !== undefined);
+
+      // Get initial counters
+      const initialCounters = await page.evaluate(() => ({
+        once: window.__nextlyticsTestOnce,
+        paramsChange: window.__nextlyticsTestParamsChange,
+        everyRender: window.__nextlyticsTestEveryRender,
+      }));
+
+      expect(initialCounters.once).toBe(1);
+      expect(initialCounters.paramsChange).toBe(1);
+      expect(initialCounters.everyRender).toBe(1);
+
+      // Soft navigate to test page using Link
+      await page.click('[data-testid="test-page-link"]');
+      await page.waitForLoadState("networkidle");
+      await page.waitForFunction(
+        (prev) => (window.__nextlyticsTestEveryRender ?? 0) > prev,
+        initialCounters.everyRender ?? 0
+      );
+
+      // Get counters after soft navigation
+      const afterNavCounters = await page.evaluate(() => ({
+        once: window.__nextlyticsTestOnce,
+        paramsChange: window.__nextlyticsTestParamsChange,
+        everyRender: window.__nextlyticsTestEveryRender,
+      }));
+
+      // "once" should still be 1 - not re-executed
+      expect(afterNavCounters.once).toBe(1);
+      // "on-params-change" should be 2 - path changed from "/" to "/test-page"
+      expect(afterNavCounters.paramsChange).toBe(2);
+      // "every-render" should be 2 - runs on every navigation
+      expect(afterNavCounters.everyRender).toBe(2);
+
+      // Navigate back to home
+      await page.click('[data-testid="home-link"]');
+      await page.waitForLoadState("networkidle");
+      await page.waitForFunction(
+        (prev) => (window.__nextlyticsTestEveryRender ?? 0) > prev,
+        afterNavCounters.everyRender ?? 0
+      );
+
+      // Get final counters
+      const finalCounters = await page.evaluate(() => ({
+        once: window.__nextlyticsTestOnce,
+        paramsChange: window.__nextlyticsTestParamsChange,
+        everyRender: window.__nextlyticsTestEveryRender,
+      }));
+
+      // "once" should still be 1
+      expect(finalCounters.once).toBe(1);
+      // "on-params-change" should be 3 - path changed again
+      expect(finalCounters.paramsChange).toBe(3);
+      // "every-render" should be 3
+      expect(finalCounters.everyRender).toBe(3);
+
+      await page.close();
+    });
   });
 });
+
+// Type augmentation for test globals
+declare global {
+  interface Window {
+    __nextlyticsTestOnce?: number;
+    __nextlyticsTestParamsChange?: number;
+    __nextlyticsTestEveryRender?: number;
+  }
+}
diff --git a/packages/core/src/backends/ga.ts b/packages/core/src/backends/ga.ts
@@ -192,19 +192,30 @@ export function googleAnalyticsBackend(
         return {
           [GA_TEMPLATE_ID]: {
             items: [
+              // External gtag.js - load once
               {
-                async: "true",
                 src: "https://www.googletagmanager.com/gtag/js?id={{measurementId}}",
-                singleton: true,
+                async: true,
+                mode: "once",
               },
+              // gtag definition and initialization - run once
               {
                 body: [
                   "window.dataLayer = window.dataLayer || [];",
                   "function gtag(){dataLayer.push(arguments);}",
+                  "window.gtag = gtag;",
                   "gtag('js', new Date());",
-                  "gtag('config', '{{measurementId}}', {{json(config)}});",
-                  "gtag('event', 'page_view');",
                 ].join("\n"),
+                mode: "once",
+              },
+              // Config - run when params change (e.g., user_id added after login)
+              {
+                body: "gtag('config', '{{measurementId}}', {{json(config)}});",
+                mode: "on-params-change",
+              },
+              // Page view - run on every navigation
+              {
+                body: "gtag('event', 'page_view');",
               },
             ],
           },
diff --git a/packages/core/src/backends/gtm.ts b/packages/core/src/backends/gtm.ts
@@ -47,18 +47,22 @@ export function googleTagManagerBackend(opts: GoogleTagManagerBackendOptions): N
       return {
         [GTM_INIT_TEMPLATE_ID]: {
           items: [
+            // GTM script loader - run once
             {
               body: [
                 "window.dataLayer = window.dataLayer || [];",
-                "dataLayer.push({{json(initialData)}});",
-                "if (!window.google_tag_manager || !window.google_tag_manager['{{containerId}}']) {",
-                "  (function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':",
-                "  new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],",
-                "  j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=",
-                "  'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);",
-                "  })(window,document,'script','dataLayer','{{containerId}}');",
-                "}",
+                "(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':",
+                "new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],",
+                "j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=",
+                "'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);",
+                "})(window,document,'script','dataLayer','{{containerId}}');",
               ].join("\n"),
+              mode: "once",
+            },
+            // Initial data push - run when params change (e.g., user logs in)
+            {
+              body: "dataLayer.push({{json(initialData)}});",
+              mode: "on-params-change",
             },
           ],
         },
@@ -69,6 +73,7 @@ export function googleTagManagerBackend(opts: GoogleTagManagerBackendOptions): N
                 "window.dataLayer = window.dataLayer || [];",
                 "dataLayer.push({{json(pageData)}});",
               ].join("\n"),
+              // default: "every-render"
             },
           ],
         },
@@ -79,6 +84,7 @@ export function googleTagManagerBackend(opts: GoogleTagManagerBackendOptions): N
                 "window.dataLayer = window.dataLayer || [];",
                 "dataLayer.push({{json(eventData)}});",
               ].join("\n"),
+              // default: "every-render"
             },
           ],
         },
diff --git a/packages/core/src/client.tsx b/packages/core/src/client.tsx
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
diff --git a/packages/core/src/server.tsx b/packages/core/src/server.tsx
diff --git a/packages/core/src/types.ts b/packages/core/src/types.ts

Original file line number	Diff line number	Diff line change
`@@ -11,7 +11,7 @@`
`11`	`11`	`"moduleResolution": "bundler",`
`12`	`12`	`"resolveJsonModule": true,`
`13`	`13`	`"isolatedModules": true,`
`14`		`- "jsx": "react-jsx",`
	`14`	`+ "jsx": "preserve",`
`15`	`15`	`"incremental": true,`
`16`	`16`	`"plugins": [`
`17`	`17`	`{`