Next.js Integration
Full-stack observability for Next.js: SSR traces, API route spans, App Router server component tracing, and Core Web Vitals from real users — zero configuration.
How It Works
Install the SDK
Run npm install @tigerops/next. The package includes a Next.js instrumentation hook, an OpenTelemetry Node.js exporter for the server runtime, and a client-side Web Vitals reporter for the browser.
Configure instrumentation.ts
Create instrumentation.ts in your project root and export a register function that calls tigerops.init(). Next.js 14+ loads this file automatically before starting the Node.js server runtime.
Add next.config.js Settings
Set experimental.instrumentationHook: true in next.config.js (Next.js 13.x) or rely on automatic loading in Next.js 14+. Add TIGEROPS_API_KEY to your environment variables in .env.local or your hosting provider.
SSR, APIs & Vitals Appear
Within seconds TigerOps receives server-side traces for page renders and API routes, Prisma/database query spans, and Core Web Vitals (LCP, CLS, INP, TTFB) from real user browsers.
What You Get Out of the Box
App Router & Server Components
Each React Server Component render and Server Action invocation creates a span with component name, data-fetching duration, and streaming status. Nested RSC trees are traced as a parent-child span hierarchy.
API Route Tracing
Both App Router Route Handlers and Pages Router API routes are auto-instrumented. Each request span captures the route path, HTTP method, status code, and duration. Middleware timing is tracked separately.
Core Web Vitals Collection
LCP, CLS, INP, FID, and TTFB are collected from real users via the web-vitals library and batched to TigerOps. Metrics are segmented by route, device type, and connection quality for actionable performance insights.
Data Layer Visibility
fetch() calls made in Server Components create child spans with URL, method, cache status, and duration. Prisma, Drizzle, and raw pg/mysql2 queries are auto-instrumented as database spans.
Edge Runtime & Middleware
Next.js Edge Middleware runs on the V8 isolate runtime. TigerOps supports the Edge runtime with a lightweight OTLP/HTTP exporter that works within Edge memory and CPU limits.
Vercel & Self-Hosted Support
Works with Vercel deployments, self-hosted Docker containers, and AWS Lambda@Edge. TIGEROPS_API_KEY set as a Vercel environment variable is all that is needed for production telemetry on Vercel.
Install & Initialize
One npm install. One instrumentation file. Full Next.js observability.
# Install the TigerOps Next.js SDK
npm install @tigerops/next
# .env.local
TIGEROPS_API_KEY=your-api-key
TIGEROPS_SERVICE_NAME=my-nextjs-app
TIGEROPS_ENVIRONMENT=production
# instrumentation.ts (project root)
export async function register() {
if (process.env.NEXT_RUNTIME === 'nodejs') {
const { init } = await import('@tigerops/next/server')
init({
serviceName: process.env.TIGEROPS_SERVICE_NAME,
// Optional: trace only a sample of requests
sampleRate: process.env.NODE_ENV === 'production' ? 0.1 : 1.0,
})
}
if (process.env.NEXT_RUNTIME === 'edge') {
const { init } = await import('@tigerops/next/edge')
init()
}
}
# next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
// Required for Next.js < 14.0 only
experimental: {
instrumentationHook: true,
},
}
module.exports = nextConfig
# app/layout.tsx — Core Web Vitals reporting
'use client'
import { useReportWebVitals } from '@tigerops/next/client'
export function Providers({ children }: { children: React.ReactNode }) {
// Reports LCP, CLS, INP, FID, TTFB to TigerOps
useReportWebVitals()
return <>{children}</>
}
# app/api/orders/route.ts — automatically traced
import { NextRequest } from 'next/server'
export async function GET(request: NextRequest) {
// This handler is auto-instrumented — no changes needed
const orders = await db.order.findMany({ take: 20 })
return Response.json(orders)
}Common Questions
Which Next.js versions are supported?
Next.js 13.4+ with the App Router is fully supported. Pages Router on Next.js 12+ is also supported. The instrumentation.ts hook requires Next.js 13.4+. For older versions, a manual require() approach is documented.
Do Core Web Vitals require any changes to my React components?
No. The @tigerops/next package exports a useReportWebVitals hook that you add once in your root layout.tsx or _app.tsx. It automatically listens for performance entries and batches them to TigerOps every 5 seconds.
Does TigerOps work with the Next.js Turbopack build tool?
Yes. @tigerops/next is a runtime package and is not affected by the build tool used. Turbopack handles compilation while TigerOps instruments the running Node.js and browser runtimes independently.
How does TigerOps handle trace context across server/client boundaries?
Server Component traces include a traceparent header that is passed to Client Components via a hidden HTML comment. The client-side SDK reads this and uses it as the parent context for client-side spans, maintaining full trace continuity.
Can I use TigerOps with Next.js deployed on Vercel Edge Functions?
Yes. Set TIGEROPS_API_KEY as a Vercel environment variable and use the edge export in @tigerops/next/edge. The edge exporter uses fetch() with OTLP/HTTP JSON format, which is compatible with the Vercel Edge runtime constraints.
Full Next.js Observability in One npm Install
SSR traces, API route spans, Core Web Vitals, and App Router observability — no code changes required.