@chip-hosting/nextjs
v1.0.1
Published
Next.js integration for the Marver Web SDK — Chip Hosting's first-party analytics (formerly Data Workbench). Client provider/hooks and edge middleware (App + Pages Router); App-Router server-side identity (server components, actions).
Downloads
267
Readme
@chip-hosting/nextjs
Next.js integration for the Marver Web SDK — Chip Hosting's first-party analytics platform (formerly Data Workbench). Provides a client provider and hooks plus edge middleware that work with both the App Router and the Pages Router, and App-Router server-side identity helpers (server components and server actions).
- Client —
AnalyticsProvider+useAnalytics/usePageViewhooks (App Router and Pages Router). - Edge — a drop-in route handler that proxies events to your Sensor.
- Server — middleware for visitor identity (router-agnostic), plus
getServerIdentityandserverTrackfor server components and actions (App Router only — they rely onnext/headers).
Router support: the client provider/hooks and the edge middleware run on both the App Router and the Pages Router. The server-side identity helpers (
getServerIdentity,serverTrack) are App Router only, since they usenext/headers.
Installation
npm install @chip-hosting/nextjs @chip-hosting/analytics@chip-hosting/analytics (the Marver Web SDK) is a peer dependency — install it alongside.
Client setup (App Router)
Wrap your app in AnalyticsProvider:
// app/layout.tsx
import { AnalyticsProvider } from '@chip-hosting/nextjs';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html>
<body>
<AnalyticsProvider
endpoint={process.env.NEXT_PUBLIC_DWB_ENDPOINT!}
clientId="my-nextjs-app"
>
{children}
</AnalyticsProvider>
</body>
</html>
);
}AnalyticsProvider props: endpoint (required), clientId (required), cookieDomain, batchSize, flushInterval, debug, useProxy, proxyEndpoint, autoCollect.
Hooks
'use client';
import { useAnalytics, usePageView } from '@chip-hosting/nextjs';
export function SignupButton() {
usePageView(); // auto-track page views on route change
const { track, identify, page, reset } = useAnalytics();
return (
<button onClick={() => track('signup_click', { plan: 'pro' })}>
Sign up
</button>
);
}useAnalytics() returns: track, page, identify, reset, flush, getVisitorId, getSessionId, getUserId.
Edge route handler
Proxy events through an Edge Function (keeps your Sensor endpoint off the client and adds geo enrichment):
// app/api/analytics/route.ts
import { createAnalyticsHandler } from '@chip-hosting/nextjs/edge';
export const runtime = 'edge';
export const POST = createAnalyticsHandler({
sensorEndpoint: process.env.DWB_SENSOR_ENDPOINT!,
clientId: 'my-nextjs-app',
});Then point the client at the proxy with useProxy / proxyEndpoint on the provider.
Server-side (middleware, components, actions)
// middleware.ts
import { createAnalyticsMiddleware } from '@chip-hosting/nextjs/server';
export const middleware = createAnalyticsMiddleware({
sensorEndpoint: process.env.DWB_SENSOR_ENDPOINT!,
clientId: 'my-nextjs-app',
});// in a server component or server action
import { getServerIdentity, serverTrack } from '@chip-hosting/nextjs/server';
const identity = await getServerIdentity();
await serverTrack('order_completed', { orderId, total });The middleware resolves visitor identity on each matched request (setting the _dwb_id cookie for new visitors) and propagates it to downstream server components, so getServerIdentity() avoids a redundant Sensor call.
License
MIT