fix: handle soft navigation in App Router

- Add soft-navigation event type to fetch scripts on client-side navigation
- Use usePathname() to detect navigation changes
- Dispatch pageView to immediate backends on soft navigation
- Revert pages router to use hard navigation (maintains existing behavior)

Author: vklimontovich

e2e/test-app/src/nextlytics.ts

@@ -8,7 +8,9 @@ import { auth } from "./auth";
 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 }> };
+type ClientAction = {
+  items: Array<{ type: "script-template"; templateId: string; params: unknown }>;
+};
 
 const CONSOLE_TEMPLATE_ID = "console-test";
 

e2e/test-app/src/pages/pages-home.tsx

@@ -1,5 +1,4 @@
 import { useSession } from "next-auth/react";
-import Link from "next/link";
 
 export default function PagesHome() {
   const { data: session } = useSession();
@@ -24,9 +23,9 @@ export default function PagesHome() {
         </div>
       )}
       <nav>
-        <Link href="/pages-test" data-testid="test-page-link">
+        <a href="/pages-test" data-testid="test-page-link">
           Test Page
-        </Link>
+        </a>
       </nav>
     </main>
   );

packages/core/src/client.tsx

@@ -10,6 +10,7 @@ import {
   useReducer,
   useRef,
 } from "react";
+import { usePathname } from "next/navigation";
 import type {
   ClientContext,
   JavascriptTemplate,
@@ -138,6 +139,24 @@ function InjectScript({
   return null;
 }
 
+/** Merge scripts by templateId - later scripts override earlier ones */
+function mergeScriptsByTemplateId(
+  scripts: TemplatizedScriptInsertion<unknown>[]
+): TemplatizedScriptInsertion<unknown>[] {
+  const byTemplateId = new Map<string, TemplatizedScriptInsertion<unknown>>();
+  const nonTemplates: TemplatizedScriptInsertion<unknown>[] = [];
+
+  for (const script of scripts) {
+    if (script.type === "script-template") {
+      byTemplateId.set(script.templateId, script);
+    } else {
+      nonTemplates.push(script);
+    }
+  }
+
+  return [...byTemplateId.values(), ...nonTemplates];
+}
+
 /** Renders initial scripts (from SSR) and dynamic scripts (from sendEvent calls) */
 function NextlyticsScripts({
   initialScripts,
@@ -146,7 +165,7 @@ function NextlyticsScripts({
 }) {
   const context = useContext(NextlyticsContext);
   if (!context) {
-    throw new Error("NextlyticsScripts should be called within NextlyticsContext")
+    throw new Error("NextlyticsScripts should be called within NextlyticsContext");
   }
 
   const { scriptsRef, subscribersRef, templates, requestId } = context;
@@ -161,20 +180,22 @@ function NextlyticsScripts({
   }, [subscribersRef]);
 
   const dynamicScripts = scriptsRef.current;
-  const allScripts = [...initialScripts, ...dynamicScripts];
+  // Merge by templateId - dynamic scripts override initial (they have newer params)
+  const allScripts = mergeScriptsByTemplateId([...initialScripts, ...dynamicScripts]);
 
   return (
     <>
-      {allScripts.flatMap((script, scriptIndex) => {
+      {allScripts.flatMap((script) => {
         if (script.type !== "script-template") return [];
         const template = templates[script.templateId];
         if (!template) {
           console.warn(`[Nextlytics] Template "${script.templateId}" not found`);
           return [];
         }
+        // Use templateId as key - same template = same component instances
         return template.items.map((item, itemIndex) => (
           <InjectScript
-            key={`${scriptIndex}:${script.templateId}:${itemIndex}`}
+            key={`${script.templateId}:${itemIndex}`}
             item={item}
             params={script.params}
             requestId={requestId}
@@ -224,6 +245,11 @@ async function sendEventToServer(
 export function NextlyticsClient(props: { ctx: NextlyticsContext; children?: ReactNode }) {
   const { requestId, scripts: initialScripts = [], templates = {} } = props.ctx;
 
+  // Track pathname for soft navigation detection
+  const pathname = usePathname();
+  const initialPathRef = useRef<string | null>(null);
+  const lastPathRef = useRef<string | null>(null);
+
   // Refs for dynamic scripts (from sendEvent calls) - stable, no re-renders
   const scriptsRef = useRef<TemplatizedScriptInsertion<unknown>[]>([]);
   const subscribersRef = useRef<Set<() => void>>(new Set());
@@ -241,11 +267,27 @@ export function NextlyticsClient(props: { ctx: NextlyticsContext; children?: Rea
 
   // Send client-init on mount (once per requestId)
   useEffect(() => {
+    initialPathRef.current = pathname;
+    lastPathRef.current = pathname;
     const clientContext = createClientContext();
     sendEventToServer(requestId, "client-init", clientContext).then(({ scripts }) => {
       if (scripts?.length) addScripts(scripts);
     });
-  }, [requestId, addScripts]);
+  }, [requestId, addScripts, pathname]);
+
+  // Detect soft navigation and fetch scripts for new page
+  useEffect(() => {
+    // Skip if this is the initial render or same path
+    if (initialPathRef.current === null || pathname === lastPathRef.current) {
+      return;
+    }
+    lastPathRef.current = pathname;
+
+    const clientContext = createClientContext();
+    sendEventToServer(requestId, "soft-navigation", clientContext).then(({ scripts }) => {
+      if (scripts?.length) addScripts(scripts);
+    });
+  }, [pathname, requestId, addScripts]);
 
   return (
     <NextlyticsContext.Provider value={contextValue}>

packages/core/src/middleware.ts

@@ -289,6 +289,38 @@ async function handleEventPost(
     // Also update "immediate" backends with client context
     after(() => updateEvent(pageRenderId, { clientContext, userContext, anonymousUserId }, ctx));
 
+    // Filter to script-template only
+    const scripts = actions.items.filter((i) => i.type === "script-template");
+    return Response.json({ ok: true, scripts: scripts.length > 0 ? scripts : undefined });
+  } else if (type === "soft-navigation") {
+    // Soft navigation in App Router - layout didn't re-render, so we need to
+    // dispatch pageView and return scripts that would have been in the initial render
+    const clientContext = payload as unknown as ClientInitPayload;
+    const serverContext = reconstructServerContext(apiCallServerContext, clientContext);
+
+    const { anonId: anonymousUserId } = await resolveAnonymousUser({
+      ctx,
+      serverContext,
+      config,
+    });
+
+    const event: NextlyticsEvent = {
+      eventId: generateId(), // New event ID for the soft navigation
+      parentEventId: pageRenderId,
+      type: "pageView",
+      collectedAt: new Date().toISOString(),
+      anonymousUserId,
+      serverContext,
+      clientContext,
+      userContext,
+      properties: {},
+    };
+
+    // Dispatch to "immediate" backends (same as middleware would do)
+    const { clientActions, completion } = dispatchEvent(event, ctx, "immediate");
+    const actions = await clientActions;
+    after(() => completion);
+
     // Filter to script-template only
     const scripts = actions.items.filter((i) => i.type === "script-template");
     return Response.json({ ok: true, scripts: scripts.length > 0 ? scripts : undefined });