@bugban/next
v1.2.0
Published
Bugban SDK for Next.js — App and Pages router, server and client, via instrumentation.
Maintainers
_brcodeReadme
@bugban/next
Bugban error and performance monitoring for Next.js — server and client.
npm install @bugban/nextWhy two entry points
A Next.js app runs in two places at once. A Server Component, route handler or middleware runs in Node; a Client Component runs in the browser. Each side needs different telemetry — slow database queries on the server, Core Web Vitals and DOM snapshots in the browser — so you wire both.
1. Server
Create instrumentation.ts at the project root (next to next.config.js). Next calls register() once per server process, before any request.
// instrumentation.ts
export async function register() {
const { registerBugban } = await import('@bugban/next');
await registerBugban({
apiKey: process.env.BUGBAN_API_KEY,
host: 'https://bugban.online',
});
}release defaults to VERCEL_GIT_COMMIT_SHA or NEXT_PUBLIC_APP_VERSION, and environment to NODE_ENV.
2. Client
// app/bugban.tsx
'use client';
import { BugbanProvider } from '@bugban/next';
export default function Bugban() {
return (
<BugbanProvider
apiKey={process.env.NEXT_PUBLIC_BUGBAN_KEY!}
host="https://bugban.online"
/>
);
}// app/layout.tsx — render it once
import Bugban from './bugban';
export default function RootLayout({ children }) {
return (
<html>
<body>
<Bugban />
{children}
</body>
</html>
);
}3. Error boundary
Next hides the real message of a server-thrown error from the client and gives you a digest instead. Passing it along is the only way to line the client-side report up with the server-side one, which captureNextError does for you.
// app/error.tsx
'use client';
import { useEffect } from 'react';
import { captureNextError } from '@bugban/next';
export default function Error({ error, reset }) {
useEffect(() => {
captureNextError(error);
}, [error]);
return <button onClick={reset}>Try again</button>;
}Add app/global-error.tsx the same way to catch failures in the root layout.
Route handlers and server actions
import { withBugbanRoute } from '@bugban/next';
export const POST = withBugbanRoute(async (req) => {
const body = await req.json();
return Response.json(await createOrder(body));
}, { name: 'orders.create' });The error is reported and then rethrown, so your own error handling still runs.
Pages Router
Use registerBugban() from instrumentation.ts exactly as above, call initBugbanClient() once in pages/_app.tsx, and report from pages/_error.tsx with captureNextError.
Slow database queries
Server-side query timing comes from @bugban/node, which is bundled in — hook Prisma, TypeORM, Knex or pg there and slow queries appear in the Performance tab.
Source maps
A production Next build is minified, so stack traces point into hashed bundles. Bugban detects this and says so instead of guessing — set productionBrowserSourceMaps: true in next.config.js to get real file and line numbers.
License
MIT