@newrelic/next
Advanced tools
This is New Relic's official Next.js framework instrumentation for use with the New Relic Node.js agent.
This module is a dependency of the agent and is installed by default when you install the agent.
This module provides instrumentation for server-side rendering via getServerSideProps, middleware, and New Relic transaction naming for both page and server requests. It does not provide any instrumentation for actions occurring during build or in client-side code. If you want telemetry data on actions occurring on the client (browser), you can inject the browser agent.
Here are documents for more in-depth explanations about transaction naming, segments/spans, and injecting the browser agent.
Note: The minimum supported Next.js version is 12.0.9. If you are using Next.js middleware the minimum supported version is 12.2.0.
Typically, most users use the version auto-installed by the agent. You can see agent install instructions here.
In some cases, installing a specific version is ideal. For example, new features or major changes might be released via a major version update to this module, prior to inclusion in the main New Relic Node.js agent.
npm install @newrelic/next
NODE_OPTIONS='-r @newrelic/next' next start
If you cannot control how your program is run, you can load the @newrelic/next module before any other module in your program. However, we strongly suggest you avoid this method at all costs. We found bundling when running next build causes problems and also will make your bundle unnecessarily large.
require('@newrelic/next')
/* ... the rest of your program ... */
If you are using next as a custom server, you're probably not running your application with the next CLI. In that scenario we recommend running the Next.js instrumentation as follows.
node -r @newrelic/next your-program.js
For more information, please see the agent installation guide.
Our API and developer documentation for writing instrumentation will be of help. We particularly recommend the tutorials and various "shim" API documentation.
Next.js is a full stack React Framework. This module augments the Node.js New Relic agent, thus any client-side actions will not be instrumented. However, below is a method of adding the New Relic Browser agent to get more information on client-side actions.
import Head from 'next/head'
import Layout, { siteTitle } from '../../components/layout'
import utilStyles from '../../styles/utils.module.css'
import Link from 'next/link'
export async function getServerSideProps() {
// You must require agent and put it within this function
// otherwise it will try to get bundled by webpack and cause errors.
const newrelic = require('newrelic')
const browserTimingHeader = newrelic.getBrowserTimingHeader()
return {
props: {
browserTimingHeader
}
}
}
export default function Home({ browserTimingHeader }) {
return (
<Layout home>
<Head>
<title>{siteTitle}</title>
</Head>
<div dangerouslySetInnerHTML={{ __html: browserTimingHeader }} />
<section className={utilStyles.headingMd}>
<p>It me</p>
<p>
This page uses server-side rendering and uses the newrelic API to inject
timing headers.
</p>
<div>
<Link href="/">
<a>← Back to home</a>
</Link>
</div>
</section>
</Layout>
)
}
For static compiled pages, you can use the copy-paste method for enabling the New Relic Browser agent.
For more information, please see the agent compatibility and requirements.
For capturing both the client and server side errors it is best to use pages/_error.js pattern recommended by Next.js documentation on Advanced Error Page Customization
This pattern can be used to send either client, server or both types of errors to New Relic.
function Error({ statusCode }) {
return (
<p>
{statusCode
? `An error ${statusCode} occurred on server`
: "An error occurred on client"}
</p>
);
}
Error.getInitialProps = ({ res, err }) => {
if (typeof window === "undefined") {
const newrelic = require('newrelic');
newrelic.noticeError(err);
} else {
window.newrelic.noticeError(err);
}
const statusCode = res ? res.statusCode : err ? err.statusCode : 404;
return { statusCode };
};
export default Error;
The example above assumes that both the New Relic Browser and Node.js agents are integrated. getInitialProps function's if statement checks whether an error was thrown on the server side (typeof window === "undefined") and if it was the case, it requires New Relic Node.js agent and sends an err with noticeError method. Otherwise it assumes the error was thrown on the front-end side, and uses the browser agent to send the error to New Relic by using window.newrelic.noticeError(err).
The module includes a suite of unit and functional tests which should be used to verify that your changes don't break existing functionality.
All tests are stored in tests/ and are written using
Tap with the extension .test.js (unit), or .tap.js (versioned).
To run the full suite, run: npm test.
Individual test scripts include:
npm run unit
npm run versioned
New Relic hosts and moderates an online forum where you can interact with New Relic employees as well as other customers to get help and share best practices. Like all official New Relic open source projects, there's a related community topic in the New Relic Explorers Hub. You can find this project's topic/threads here:
We encourage your contributions to improve the Next.js instrumentation module! Keep in mind that when you submit your pull request, you'll need to sign the CLA via the click-through using CLA-Assistant. You only have to sign the CLA one time per project.
If you have any questions, or want to execute our corporate CLA (which is required if your contribution is on behalf of a company), drop us an email at opensource@newrelic.com.
A note about vulnerabilities
As noted in our security policy, New Relic is committed to the privacy and security of our customers and their data. We believe that providing coordinated disclosure by security researchers and engaging with the security community are important means to achieve our security goals.
If you believe you have found a security vulnerability in this project or any of New Relic's products or websites, we welcome and greatly appreciate you reporting it to New Relic through HackerOne.
If you would like to contribute to this project, review these guidelines.
To all contributors, we thank you! Without your contribution, this project would not be what it is today. We also host a community project page dedicated to New Relic Next.js instrumentation.
New Relic Next.js instrumentation is licensed under the Apache 2.0 License.
New Relic Next.js instrumentation also uses source code from third-party libraries. You can find the full details on which libraries are used and the terms under which they are licensed in the third-party notices document.
v0.3.0 (2022-07-27)
The minimum supported version is now Node v14. For further information on our support policy, see: https://docs.newrelic.com/docs/agents/nodejs-agent/getting-started/compatibility-requirements-nodejs-agent.
Added support for Node 18.x
Updated sample app to use http.get instead of fetch to make subrequests to API to avoid async context propagation breakage in Node 18.
FAQs
Next.js instrumentation for the New Relic Node.js agent.
The npm package @newrelic/next receives a total of 70,981 weekly downloads. As such, @newrelic/next popularity was classified as popular.
We found that @newrelic/next demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.