Next.js SDK

Automatic API tracking for Next.js. Works in Server Components, API Routes, and Server Actions.

Installation

npm install @outbound_iq/nextjs

Setup

1. Create instrumentation.ts at the project root or inside src/ (same convention as Next.js):

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    await import('@outbound_iq/nextjs/register');
  }
}

2. Enable the instrumentation hook when your Next.js version requires it:

Next.js 15+ — usually no experimental.instrumentationHook needed.
Next.js 13.2 – 14.x — add this to next.config.js:

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    instrumentationHook: true,
  },
};

module.exports = nextConfig;

3. Add to .env:

OUTBOUNDIQ_KEY=your_api_key_here

Server Components

Fetch calls in Server Components are automatically tracked:

// app/page.tsx
export default async function Page() {
  // Automatically tracked!
  const data = await fetch('https://api.example.com/data');
  return <div>{JSON.stringify(await data.json())}</div>;
}

API Routes

Node route handlers are covered by register (see instrumentation.ts). For Edge routes, or when you want an explicit wrapper, use trackFetch from the /edge entry (not the package root):

// app/api/data/route.ts
import { trackFetch } from '@outbound_iq/nextjs/edge';

export async function GET() {
  const res = await trackFetch('https://api.example.com/data');
  return Response.json(await res.json());
}

User Context with Middleware

Pass a getUserContext callback that returns whatever identifiers you use (session cookie, JWT, etc.). Example without tying the docs to a specific auth library:

// middleware.ts
import { withOutboundIQ } from '@outbound_iq/nextjs/middleware';
import { NextResponse } from 'next/server';

export default withOutboundIQ(async (request) => {
  return NextResponse.next();
}, {
  getUserContext: async (request) => {
    const userId = request.cookies.get('user_id')?.value;
    return userId ? { userId, context: 'authenticated' } : null;
  },
});

Axios Tracking

Axios helpers are exported from the /edge subpath (safe for shared client modules). The package root does not export them.

import axios from 'axios';
import { addAxiosTracking, createTrackedAxios } from '@outbound_iq/nextjs/edge';

// Option 1: Add tracking to existing axios instance
const api = axios.create({ baseURL: 'https://api.stripe.com/v1' });
addAxiosTracking(api);

// Option 2: Create a new tracked axios instance
const trackedApi = createTrackedAxios(axios, {
  baseURL: 'https://api.twilio.com',
});

await api.get('/charges');
await trackedApi.post('/messages', { Body: 'Hello!' });

Test Your Integration

From your project root, OUTBOUNDIQ_KEY is read from the environment; recent CLI versions also load .env / .env.local automatically.

npx outboundiq-test