Next.js

Server-Side Monitoring for Next.js Applications

Free on every plan, including the free one

Start for free Documentation

Where to get it

View on npm

npm

Requirements Next.js 13.4+ with the App Router, Node.js runtime

Package name @dockcodes/dock-ray-next

Pricing Free

What it is for

The official DockRay integration for Next.js lets you monitor errors and performance in Next.js applications. It automatically reports server-side, Edge Runtime, and middleware errors, with optional JavaScript error reporting from the browser.

The integration supports Next.js 14 and 15 and applications using both the App Router and Pages Router.

Next.js Error Monitoring

DockRay integrates with Next.js error reporting and lets you collect issues occurring across different parts of your application.

Errors can be monitored in areas including:

Server Components,
Route Handlers,
Server Actions,
streaming rendering,
Pages Router and API Routes,
middleware and Edge Runtime.

Events can include information about the router, route pattern, route type, and rendering source, making it easier to identify where an issue occurred.

Performance Monitoring

DockRay lets you monitor request processing times and transactions in your Next.js application. The frequency of data collection can be controlled using a sampling rate.

JavaScript Error Monitoring

You can optionally enable reporting of JavaScript errors that occur in the user's browser. Events are first sent to an endpoint in your own Next.js application and then forwarded to DockRay.

This ensures that your project's private key remains exclusively on the server and is never exposed in the application's public code.

Edge Runtime and Middleware

The integration provides a separate entry point designed for the Edge Runtime environment. This allows errors occurring in middleware and other parts of the application running on the Edge to be reported.

Privacy and Security

Sensitive headers such as Authorization, Cookie, Set-Cookie, and X-Api-Key are removed from reported data.

Sending the IP address and user agent is optional and must be enabled separately in the configuration.

Vercel Integration

For applications deployed on Vercel, DockRay can automatically use deployment environment and application version information, making it easier to distinguish production from preview deployments.

Installation

<h3>Package Installation</h3>

<p>Install DockRay using npm:</p>

<pre><code>npm install @dockcodes/dock-ray-next</code></pre>

<h3>Configuration</h3>

<p>Add your DockRay project credentials to your environment variables:</p>

<pre><code>RAY_TOKEN=project-token

RAY_PRIVATE_KEY=project-private-key

RAY_TRACES_SAMPLE_RATE=0.2</code></pre>

<p>

You can find your project token and private key in the DockRay dashboard.

</p>

<p>

<code>RAY_PRIVATE_KEY</code> must remain a server-only environment variable. Do not use the <code>NEXT_PUBLIC_</code> prefix, as this would expose the key in the application's public client-side code.

</p>

<p>

Without a configured token and private key, the integration remains inactive and does not send any data.

</p>

<h3>Enabling Error Reporting</h3>

<p>

In the <code>instrumentation.ts</code> file in the project root, initialize DockRay and configure error handling:

</p>

<pre class="language-js"><code>import {

initRay,

rayRequestError

} from '@dockcodes/dock-ray-next';

export function register() {

initRay();

}

export const></code></pre><code>

<p>

Once configured, DockRay can report errors captured by Next.js, including errors from Server Components, Route Handlers, Server Actions, and streaming rendering.

</p></code>

How to use it

The integration reports exceptions on its own. This is for the reports you send deliberately.

import { withRay } from '@dockcodes/dock-ray-next';

export default withRay(async function handler(req, res) {
    const order = await processOrder(req.body);

    res.status(200).json({
        success: true,
        order
    });
});