@goliapkg/sentori-next 0.1.0 → 0.2.1

package/README.md

@@ -64,11 +64,16 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 ```tsx
 // app/error.tsx
 'use client'
-import { SentoriErrorBoundary } from '@goliapkg/sentori-next/client'
-
-export default function Error({ error, reset }: { error: Error; reset: () => void }) {
-  // Next already calls our boundary; here we render the fallback UI.
-  // The capture happened upstream via SentoriProvider's hook.
+import { useReportNextError } from '@goliapkg/sentori-next/app-router'
+
+export default function Error({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string }
+  reset: () => void
+}) {
+  useReportNextError(error) // captureError once per error instance
   return (
     <div>
       <h2>Something went wrong</h2>
@@ -78,7 +83,28 @@ export default function Error({ error, reset }: { error: Error; reset: () => voi
 }
 ```
 
-For a global catch-all, do the same in `app/global-error.tsx`.
+`useReportNextError` calls `captureError` once per error instance
+and picks up Next's `error.digest` as a tag so the dashboard can
+correlate the client report with the server error.
+
+For a global catch-all, drop the same component into
+`app/global-error.tsx`.
+
+### Navigation breadcrumbs (any layout)
+
+```tsx
+// app/Shell.tsx — client wrapper mounted from app/layout.tsx
+'use client'
+import { useNextRouter } from '@goliapkg/sentori-next/app-router'
+
+export function Shell({ children }: { children: React.ReactNode }) {
+  useNextRouter() // nav breadcrumb on every pathname change
+  return <>{children}</>
+}
+```
+
+First mount does not emit a breadcrumb; only real pathname
+transitions are recorded.
 
 ## What gets captured
 
@@ -102,6 +128,7 @@ the same signature. `serverInit()` is Node-only because Edge lacks
 | `@goliapkg/sentori-next/client` | App Router client components, `clientInit`, `SentoriProvider`, `<SentoriErrorBoundary>`, hooks |
 | `@goliapkg/sentori-next/server` | `instrumentation.ts`, `serverInit`, `onRequestError` |
 | `@goliapkg/sentori-next/instrumentation` | one-line `instrumentation.ts` re-export |
+| `@goliapkg/sentori-next/app-router` | `useNextRouter`, `useReportNextError` — client-only App Router hooks |
 
 ## Versioning
 

package/lib/app-router.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Subscribe to App Router pathname transitions and push a `nav`
+ * breadcrumb on every change. Mount once in a layout's client
+ * component (e.g. a `<Shell>` in `app/layout.tsx`):
+ *
+ *     'use client'
+ *     import { useNextRouter } from '@goliapkg/sentori-next/app-router'
+ *     export function Shell({ children }: { children: React.ReactNode }) {
+ *       useNextRouter()
+ *       return children
+ *     }
+ *
+ * First mount does NOT emit a breadcrumb — only real transitions.
+ *
+ * Intentionally does not read `useSearchParams()` — that hook
+ * requires a Suspense boundary in Next.js 14+ which complicates
+ * adoption. Pathname alone covers the breadcrumb story.
+ */
+export declare function useNextRouter(): void;
+/**
+ * Capture an error from an App Router `error.tsx` file. Idiomatic
+ * usage:
+ *
+ *     // app/error.tsx
+ *     'use client'
+ *     import { useReportNextError } from '@goliapkg/sentori-next/app-router'
+ *     export default function ErrorPage({ error, reset }: {
+ *       error: Error & { digest?: string }
+ *       reset: () => void
+ *     }) {
+ *       useReportNextError(error)
+ *       return (
+ *         <div>
+ *           <h2>Something went wrong.</h2>
+ *           <button onClick={reset}>Try again</button>
+ *         </div>
+ *       )
+ *     }
+ *
+ * The hook calls captureError exactly once per error instance
+ * (subsequent renders with the same error are no-ops). Picks up
+ * Next's `digest` field as a tag so the dashboard can correlate
+ * the client report with the server error.
+ */
+export declare function useReportNextError(error: Error & {
+    digest?: string;
+}): void;
+//# sourceMappingURL=app-router.d.ts.map

package/lib/app-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-router.d.ts","sourceRoot":"","sources":["../src/app-router.ts"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAWpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,KAAK,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAY3E"}

package/lib/app-router.js

@@ -0,0 +1,77 @@
+// App Router helpers for Next.js 14+. Imports from `next/navigation`
+// (Next-side), so this module is client-only and is published under
+// the `/app-router` subpath so the server bundle never tries to load
+// `next/navigation` during instrumentation.
+'use client';
+import { addBreadcrumb, captureError } from '@goliapkg/sentori-javascript';
+import { usePathname } from 'next/navigation';
+import { useEffect, useRef } from 'react';
+/**
+ * Subscribe to App Router pathname transitions and push a `nav`
+ * breadcrumb on every change. Mount once in a layout's client
+ * component (e.g. a `<Shell>` in `app/layout.tsx`):
+ *
+ *     'use client'
+ *     import { useNextRouter } from '@goliapkg/sentori-next/app-router'
+ *     export function Shell({ children }: { children: React.ReactNode }) {
+ *       useNextRouter()
+ *       return children
+ *     }
+ *
+ * First mount does NOT emit a breadcrumb — only real transitions.
+ *
+ * Intentionally does not read `useSearchParams()` — that hook
+ * requires a Suspense boundary in Next.js 14+ which complicates
+ * adoption. Pathname alone covers the breadcrumb story.
+ */
+export function useNextRouter() {
+    const pathname = usePathname();
+    const prevRef = useRef(null);
+    useEffect(() => {
+        const prev = prevRef.current;
+        if (prev !== null && prev !== pathname) {
+            addBreadcrumb({ data: { from: prev, to: pathname }, type: 'nav' });
+        }
+        prevRef.current = pathname;
+    }, [pathname]);
+}
+/**
+ * Capture an error from an App Router `error.tsx` file. Idiomatic
+ * usage:
+ *
+ *     // app/error.tsx
+ *     'use client'
+ *     import { useReportNextError } from '@goliapkg/sentori-next/app-router'
+ *     export default function ErrorPage({ error, reset }: {
+ *       error: Error & { digest?: string }
+ *       reset: () => void
+ *     }) {
+ *       useReportNextError(error)
+ *       return (
+ *         <div>
+ *           <h2>Something went wrong.</h2>
+ *           <button onClick={reset}>Try again</button>
+ *         </div>
+ *       )
+ *     }
+ *
+ * The hook calls captureError exactly once per error instance
+ * (subsequent renders with the same error are no-ops). Picks up
+ * Next's `digest` field as a tag so the dashboard can correlate
+ * the client report with the server error.
+ */
+export function useReportNextError(error) {
+    const seenRef = useRef(null);
+    useEffect(() => {
+        if (seenRef.current === error)
+            return;
+        seenRef.current = error;
+        captureError(error, {
+            tags: {
+                'next.digest': error.digest ?? '',
+                source: 'next.error.tsx',
+            },
+        });
+    }, [error]);
+}
+//# sourceMappingURL=app-router.js.map

package/lib/app-router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-router.js","sourceRoot":"","sources":["../src/app-router.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,oEAAoE;AACpE,qEAAqE;AACrE,4CAA4C;AAE5C,YAAY,CAAA;AAEZ,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAA;AAC1E,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,OAAO,CAAA;AAEzC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,aAAa;IAC3B,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAA;IAC9B,MAAM,OAAO,GAAG,MAAM,CAAgB,IAAI,CAAC,CAAA;IAE3C,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAA;QAC5B,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;YACvC,aAAa,CAAC,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAA;QACpE,CAAC;QACD,OAAO,CAAC,OAAO,GAAG,QAAQ,CAAA;IAC5B,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAA;AAChB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAkC;IACnE,MAAM,OAAO,GAAG,MAAM,CAAe,IAAI,CAAC,CAAA;IAC1C,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,OAAO,CAAC,OAAO,KAAK,KAAK;YAAE,OAAM;QACrC,OAAO,CAAC,OAAO,GAAG,KAAK,CAAA;QACvB,YAAY,CAAC,KAAK,EAAE;YAClB,IAAI,EAAE;gBACJ,aAAa,EAAE,KAAK,CAAC,MAAM,IAAI,EAAE;gBACjC,MAAM,EAAE,gBAAgB;aACzB;SACF,CAAC,CAAA;IACJ,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAA;AACb,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@goliapkg/sentori-next",
-  "version": "0.1.0",
-  "description": "Next.js adapter for Sentori — instrumentation.ts hooks, App Router error boundary, env-driven provider built on @goliapkg/sentori-react.",
+  "version": "0.2.1",
+  "description": "Next.js adapter for Sentori — instrumentation.ts hooks, App Router error boundary, navigation tracing, env-driven provider built on @goliapkg/sentori-react.",
   "license": "MIT",
   "homepage": "https://sentori.golia.jp",
   "repository": {
@@ -38,6 +38,10 @@
     "./instrumentation": {
       "types": "./lib/instrumentation.d.ts",
       "default": "./lib/instrumentation.js"
+    },
+    "./app-router": {
+      "types": "./lib/app-router.d.ts",
+      "default": "./lib/app-router.js"
     }
   },
   "files": [
@@ -56,9 +60,9 @@
     "react": ">=18"
   },
   "dependencies": {
-    "@goliapkg/sentori-core": "0.1.0",
-    "@goliapkg/sentori-javascript": "0.2.0",
-    "@goliapkg/sentori-react": "0.1.0"
+    "@goliapkg/sentori-core": "0.3.0",
+    "@goliapkg/sentori-javascript": "0.3.1",
+    "@goliapkg/sentori-react": "0.4.1"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/app-router.ts

@@ -0,0 +1,80 @@
+// App Router helpers for Next.js 14+. Imports from `next/navigation`
+// (Next-side), so this module is client-only and is published under
+// the `/app-router` subpath so the server bundle never tries to load
+// `next/navigation` during instrumentation.
+
+'use client'
+
+import { addBreadcrumb, captureError } from '@goliapkg/sentori-javascript'
+import { usePathname } from 'next/navigation'
+import { useEffect, useRef } from 'react'
+
+/**
+ * Subscribe to App Router pathname transitions and push a `nav`
+ * breadcrumb on every change. Mount once in a layout's client
+ * component (e.g. a `<Shell>` in `app/layout.tsx`):
+ *
+ *     'use client'
+ *     import { useNextRouter } from '@goliapkg/sentori-next/app-router'
+ *     export function Shell({ children }: { children: React.ReactNode }) {
+ *       useNextRouter()
+ *       return children
+ *     }
+ *
+ * First mount does NOT emit a breadcrumb — only real transitions.
+ *
+ * Intentionally does not read `useSearchParams()` — that hook
+ * requires a Suspense boundary in Next.js 14+ which complicates
+ * adoption. Pathname alone covers the breadcrumb story.
+ */
+export function useNextRouter(): void {
+  const pathname = usePathname()
+  const prevRef = useRef<null | string>(null)
+
+  useEffect(() => {
+    const prev = prevRef.current
+    if (prev !== null && prev !== pathname) {
+      addBreadcrumb({ data: { from: prev, to: pathname }, type: 'nav' })
+    }
+    prevRef.current = pathname
+  }, [pathname])
+}
+
+/**
+ * Capture an error from an App Router `error.tsx` file. Idiomatic
+ * usage:
+ *
+ *     // app/error.tsx
+ *     'use client'
+ *     import { useReportNextError } from '@goliapkg/sentori-next/app-router'
+ *     export default function ErrorPage({ error, reset }: {
+ *       error: Error & { digest?: string }
+ *       reset: () => void
+ *     }) {
+ *       useReportNextError(error)
+ *       return (
+ *         <div>
+ *           <h2>Something went wrong.</h2>
+ *           <button onClick={reset}>Try again</button>
+ *         </div>
+ *       )
+ *     }
+ *
+ * The hook calls captureError exactly once per error instance
+ * (subsequent renders with the same error are no-ops). Picks up
+ * Next's `digest` field as a tag so the dashboard can correlate
+ * the client report with the server error.
+ */
+export function useReportNextError(error: Error & { digest?: string }): void {
+  const seenRef = useRef<Error | null>(null)
+  useEffect(() => {
+    if (seenRef.current === error) return
+    seenRef.current = error
+    captureError(error, {
+      tags: {
+        'next.digest': error.digest ?? '',
+        source: 'next.error.tsx',
+      },
+    })
+  }, [error])
+}