@zetalyx/nextjs
v2.2.1
Published
Zetalyx SDK for Next.js - full-stack error & event tracking
Readme
@zetalyx/nextjs
Next.js integration for Zetalyx — full-stack error capture with minimal setup.
Installation
npm install @zetalyx/nextjs @zetalyx/react @zetalyx/browser @zetalyx/nodeMinimum Setup (2 files + env)
This is all you need for full-stack error capture:
1. Environment Variables
# .env.local
# Server-side (API token)
ZETALYX_PROJECT_TOKEN=ptk_api_live_acme-corp_web-app_q7r8...
# Client-side (SDK token)
NEXT_PUBLIC_ZETALYX_PROJECT_TOKEN=ptk_sdk_live_acme-corp_web-app_a1b2...
# Optional
ZETALYX_DEBUG=true
ZETALYX_ENDPOINT=https://your-custom-api.example.com2. Server-side: instrumentation.ts
// instrumentation.ts
import { initZetalyxServer } from '@zetalyx/nextjs';
export function register() {
initZetalyxServer();
}Captures all uncaught exceptions and unhandled promise rejections on the server.
3. Client-side: add provider to layout
// app/layout.tsx
import { ZetalyxClientProvider } from '@zetalyx/nextjs';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html>
<body>
<ZetalyxClientProvider errorBoundary>
{children}
</ZetalyxClientProvider>
</body>
</html>
);
}Auto-captures window errors, unhandled promise rejections, and React render errors.
That's it. You now have full-stack error capture.
Removal
- Delete
instrumentation.ts(or remove theinitZetalyxServer()call) - Remove
<ZetalyxClientProvider>fromlayout.tsx - Delete the env vars
No business logic files are touched. No per-route wrappers to revert.
Optional Enhancements
Everything below is optional — use only if you need more granular tracking.
Middleware tracking (request-level metrics)
// middleware.ts
import { withZetalyxMiddleware } from '@zetalyx/nextjs';
import { NextResponse, type NextRequest } from 'next/server';
function middleware(request: NextRequest) {
return NextResponse.next();
}
export default withZetalyxMiddleware(middleware);Tracks: HTTP method, path, status code, duration, client IP, user agent.
Per-route API wrapping (route-specific metadata)
// app/api/users/route.ts
import { withZetalyx } from '@zetalyx/nextjs';
import { NextResponse } from 'next/server';
export const GET = withZetalyx(async (request) => {
const users = await db.getUsers();
return NextResponse.json(users);
});Adds per-route context: method, path, status code, duration.
Server action wrapping (action-specific metadata)
// app/actions.ts
'use server';
import { withZetalyxAction } from '@zetalyx/nextjs';
export const createPost = withZetalyxAction(async (formData: FormData) => {
const title = formData.get('title') as string;
return await db.createPost({ title });
});Adds action name to error reports.
Error page hook (error page context)
// app/error.tsx
'use client';
import { useZetalyxError } from '@zetalyx/nextjs';
export default function Error({
error,
reset,
}: {
error: Error & { digest?: string };
reset: () => void;
}) {
useZetalyxError(error);
return (
<div>
<h2>Something went wrong</h2>
<button onClick={reset}>Try again</button>
</div>
);
}Global error component (catch-all UI)
// app/global-error.tsx
export { ZetalyxGlobalError as default } from '@zetalyx/nextjs';Provider Props
ZetalyxClientProvider accepts all @zetalyx/react provider props:
<ZetalyxClientProvider
projectToken="ptk_sdk_live_..." // Optional if NEXT_PUBLIC_ZETALYX_PROJECT_TOKEN is set
userId={session?.user?.id} // Optional user identification
autoCapture={true} // Auto-capture window errors (default: true)
captureClicks={false} // Auto-track clicks on interactive elements (default: false)
errorBoundary={true} // Wrap children in error boundary (default: false)
errorFallback={<ErrorUI />} // Custom error boundary fallback
onError={(error, info) => {}} // Error boundary callback
enabled={true} // Kill switch — false = zero side effects (default: true)
>
{children}
</ZetalyxClientProvider>Disabling the SDK
Set enabled={false} on the provider (client) or pass enabled: false to initZetalyxServer() config (server). When disabled:
- No event listeners attached
- No network requests made
- No timers started
- All tracking methods are silent no-ops
- Provider renders children without side effects
This lets you disable Zetalyx without removing code — useful for dev/staging.
Custom Endpoint
Override the default API endpoint via env var or config:
ZETALYX_ENDPOINT=http://localhost:3001Or pass directly:
initZetalyxServer({ endpoint: 'http://localhost:3001' });<ZetalyxClientProvider endpoint="http://localhost:3001">License
MIT