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,
@@ -146,7 +147,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;
@@ -224,6 +225,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 +247,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 });