Ops AI Next.js APM

Instrument your Next.js app with the Middleware Next.js SDK so Ops AI can analyze production issues and (when applicable) propose solution PRs.

You’ll learn how to: (1) install the APM + sourcemap uploader, (2) update next.config.js to build & upload sourcemaps, and (3) add an instrumentation file.

Delivery Modes (choose one)

• With Infra Agent: The SDK sends telemetry to the mw-agent on the host, and the agent forwards it to the Middleware. Route: SDK → mw-agent → Middleware.
• Without Infra agent: The SDK sends directly to the Middleware over HTTPS. Route: SDK → Middleware (set target: "https://<MW_UID>.middleware.io:443").
• Vercel: You don’t control the underlying server, so you can’t install mw-agent. The SDK sends to a Vercel integration, which forwards to Middleware. Route: SDK → vercel-integration → Middleware (target: "vercel").

1. Install the APM + Sourcemap Uploader (Bash)

Add the Next.js APM package and sourcemap uploader to your project.

1npm i @middleware.io/agent-apm-nextjs @middleware.io/sourcemap-uploader

2. Update next.config.js

This enables production browser source maps and configures the middleware source map uploader. Replace "<ACCOUNT-KEY>" with your app’s key. If you’re using Next.js < 14.0, remove the serverComponentsExternalPackages line if it exists in your project.

1// next.config.js
2const MiddlewareWebpackPlugin =
3  require("@middleware.io/sourcemap-uploader/dist/webpack-plugin").default;
4
5const nextConfig = {
6  // ...your existing config
7  productionBrowserSourceMaps: true, // for client-side sourcemaps
8
9  webpack: (config, { isServer }) => {
10    config.plugins.push(
11      new MiddlewareWebpackPlugin(
12        "<ACCOUNT-KEY>" // Account key of the application.
13      )
14    );
15    return config;
16  },
17};
18
19module.exports = nextConfig;

Why this matters: Sourcemaps enable Ops AI to resolve minified stack traces back to readable source code during error analysis.

3. Create instrumentation.ts

Create instrumentation.ts (or .js) in your project root (or under src/). Then pick one of the three variants below that matches your delivery mode.

A. Without Infra Agent (no target)

The SDK sends the data to the mw-agent on the host; the agent forwards it to the Middleware. Do not set the target.

1// instrumentation.ts
2// @ts-expect-error: The NextJS APM does not currently have full type declarations
3import tracker from '@middleware.io/agent-apm-nextjs';
4
5export function register() {
6  tracker.track({
7    serviceName: "<SERVICE-NAME>",
8    accessToken: "<MW_API_KEY>",
9    enableExceptionHandling: true,
10    customResourceAttributes: {
11      "app.version": "<1.0.0>"
12    }
13  });
14}

B. With Infra Agent (direct to Middleware)

Set target to your workspace URL so the SDK ships directly to Middleware.

1// instrumentation.ts
2// @ts-expect-error: The NextJS APM does not currently have full type declarations
3import tracker from '@middleware.io/agent-apm-nextjs';
4
5export function register() {
6  tracker.track({
7    serviceName: "<SERVICE-NAME>",
8    accessToken: "<MW_API_KEY>",
9    target: "https://<MW_UID>.middleware.io:443",
10    enableExceptionHandling: true,
11    customResourceAttributes: {
12      "app.version": "1.0.0"
13    }
14  });
15}

C. Vercel Deployment (send to Vercel integration)

Use target: "vercel" so the SDK forwards to the Vercel integration, which then ships to Middleware.

1// instrumentation.ts
2// @ts-expect-error: The NextJS APM does not currently have full type declarations
3import tracker from '@middleware.io/agent-apm-nextjs';
4
5export function register() {
6  tracker.track({
7    serviceName: "<SERVICE-NAME>",
8    accessToken: "<MW_API_KEY>",
9    target: "vercel",
10    enableExceptionHandling: true,
11    customResourceAttributes: {
12      "app.version": "1.0.0"
13    }
14  });
15}

Manual Exception Capture (pages router)

If you use the Pages router, manually capture thrown errors so they’re visible in Ops AI.

1// @ts-ignore
2import tracker from '@middleware.io/agent-apm-nextjs';
3
4try {
5  // Code that might throw
6  riskyOperation();
7} catch (error) {
8  tracker.captureException(error);
9}

(Recommended) VCS Metadata (Bash)

If a .git directory isn’t present at runtime (e.g., container builds), set these so Ops AI can tie incidents to the correct repo/commit for code mapping and PR suggestions.

1MW_VCS_COMMIT_SHA=$(git rev-parse HEAD)
2MW_VCS_REPOSITORY_URL=$(git config --get remote.origin.url)

These are just example commands to fetch values from Git. You can set these environment variables in any way that fits your workflow, such as through your CI/CD pipeline or other automation tools.