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.
Need assistance or want to learn more about Middleware? Contact our support team at [email protected] or join our Slack channel.