@serge-ai/nextjs
v0.2.2
Published
Serge for Next.js — App Router-aware <Analytics /> + <DetectionPixel /> with auto pageview tracking on route changes.
Maintainers
yannborieReadme
@serge-ai/nextjs
No cookies. No localStorage by default. No consent banner required. ePrivacy Art. 5(3) compliant by construction.
Next.js App Router integration for Serge. Drop-in <Analytics /> + <DetectionPixel /> with automatic pageview emission on every route change via usePathname / useSearchParams.
pnpm add @serge-ai/nextjs
# or
npm install @serge-ai/nextjsIf you're not using the App Router → use @serge-ai/react instead. Pages Router's next/router events handle what we'd need.
Quick start
// app/layout.tsx
import { Analytics, DetectionPixel } from '@serge-ai/nextjs'
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html>
<body>
{children}
<Analytics token="srg_pub_xxxxxxxxxxxxxxxxxxxxxxxxxx" />
<DetectionPixel token="srg_pub_xxxxxxxxxxxxxxxxxxxxxxxxxx" />
</body>
</html>
)
}That's it. Every route change in your app fires a pageview automatically; non-JS agents get caught by the pixel.
To emit a custom event from any client component:
'use client'
import { track } from '@serge-ai/nextjs'
export function CheckoutButton() {
return (
<button onClick={() => track('checkout_started', { plan: 'pro' })}>
Check out
</button>
)
}What this does that @serge-ai/react doesn't
- Listens to
usePathname()+useSearchParams()to firepageview()on every App Router navigation. The plain React<Analytics />relies on the History API, which Next.js intercepts in ways that can hide route changes from a generic listener. - Wraps the search-params listener in
<Suspense>as Next.js requires —useSearchParamsforces dynamic rendering of its non-Suspense parent, which would defeat static rendering for the entire layout. The internal Suspense fallback isnull, so the page tree is visually identical.
API re-exports
import { init, track, consent, pageview, DetectionPixel } from '@serge-ai/nextjs'These are re-exports from @serge-ai/js and @serge-ai/react so consumers can import everything from one path. See @serge-ai/js docs for the full reference.
SSR safety
Every browser-API access is guarded inside useEffect. The component is marked 'use client'. Safe to import from a server component layout — the Suspense wrapper isolates the dynamic-rendering bailout to the inner zero-DOM component.
Next.js + React versions
next@>=14(peer dependency)react@^18 || ^19(peer dependency)
Works in App Router projects. Pages Router → use @serge-ai/react.
Bundle size
Under 6 KB gzipped (excluding react, next, @serge-ai/js, and @serge-ai/react, which the host already provides). size-limit enforces this in CI.
License
MIT © Superstellar LLC. See LICENSE.