@usesentinel/nextjs

Sentinel wrapper for Next.js - Track your API requests automatically.

Installation

npm install @usesentinel/nextjs
# or
yarn add @usesentinel/nextjs
# or
pnpm add @usesentinel/nextjs

Usage

API Routes (Pages Router)

Wrap your API route handlers with withSentinel:

// pages/api/health.ts
import { withSentinel, type SentinelContext } from "@usesentinel/nextjs";
import type { NextApiRequest, NextApiResponse } from "next";

export default withSentinel(async (req: NextApiRequest & { sentinel?: SentinelContext }, res: NextApiResponse) => {
  res.json({ status: "ok" });
});

Route Handlers (App Router)

Wrap your route handlers with withSentinelRouteHandler:

// app/api/health/route.ts
import { withSentinelRouteHandler, type SentinelContext } from "@usesentinel/nextjs";
import { NextRequest, NextResponse } from "next/server";

export const GET = withSentinelRouteHandler(async (req: NextRequest & { sentinel?: SentinelContext }) => {
  return NextResponse.json({ status: "ok" });
});

Configuration

The SDK automatically reads from environment variables:

• SENTINEL_API_KEY (required) - Your Sentinel API key

You can also pass options directly:

export default withSentinel(
  async (req, res) => {
    res.json({ status: "ok" });
  },
  {
    apiKey: "sk_...", // Optional if SENTINEL_API_KEY is set
    batchSize: 50, // Optional, default 50
    flushInterval: 5000, // Optional, default 5000ms
    excludePaths: ["/api/health", "/api/metrics"], // Optional
  }
);

Setting User Context

You can set userId for a request to track user behavior:

API Routes (Pages Router)

import { withSentinel, setUserId, type SentinelContext } from "@usesentinel/nextjs";
import type { NextApiRequest, NextApiResponse } from "next";

export default withSentinel(async (req: NextApiRequest & { sentinel?: SentinelContext }, res: NextApiResponse) => {
  // Get user from your auth system
  const user = await getCurrentUser(req);

  // Identify the user making the request
  if (req.sentinel) {
    setUserId(req.sentinel.requestId, user.id);
  }

  res.json({ users: [] });
});

Route Handlers (App Router)

import { withSentinelRouteHandler, setUserId, type SentinelContext } from "@usesentinel/nextjs";
import { NextRequest, NextResponse } from "next/server";

export const GET = withSentinelRouteHandler(async (req: NextRequest & { sentinel?: SentinelContext }) => {
  // Get user from your auth system
  const user = await getCurrentUser(req);

  // Identify the user making the request
  if (req.sentinel) {
    setUserId(req.sentinel.requestId, user.id);
  }

  return NextResponse.json({ users: [] });
});

Tracking Steps

You can track sub-operations within a request:

import { withSentinel, registerStep, type SentinelContext } from "@usesentinel/nextjs";
import type { NextApiRequest, NextApiResponse } from "next";

export default withSentinel(async (req: NextApiRequest & { sentinel?: SentinelContext }, res: NextApiResponse) => {
  if (!req.sentinel) {
    return res.status(500).json({ error: "Sentinel not initialized" });
  }

  // Track a database query
  const endDbStep = registerStep(req.sentinel.requestId, "db_query", {
    table: "users",
    operation: "SELECT",
  });
  const users = await db.query("SELECT * FROM users");
  endDbStep();

  res.json(users);
});

How it works

The wrapper automatically:

• Tracks all incoming requests
• Captures request/response metadata
• Batches events and sends them to Sentinel API
• Handles errors gracefully with automatic retries
• Supports exponential backoff for failed requests

Events are batched and sent automatically, so there's minimal performance impact. Failed requests are automatically retried with exponential backoff (up to 3 retries by default).