Update NextJS examples since @newrelic/next was deprecated

[gwkline]

Description

Since the deprecation of @newrelic/next (https://github.com/newrelic/node-newrelic/releases/tag/v12.0.0), it seems like the NextJS examples are a bit out of date. I see some documentation referring to the (now stable) NextJS instrumentation.js approach, I see some using the old @newrelic/next package. Do we need both of these? Will only one of these be sufficient?

TLDR is I am struggling to find the current "best" approach (e.g. why would I want to use NODE_OPTIONS="-r newrelic" over using instrumentation.js).

Acceptance Criteria

Just pointing us in the right direction would be huge, maybe some updated docs would be nice.

Design Consideration/Limitations

Why is this the route we should take to achieve our goal?
What can't be achieved within this story?

Dependencies

documentation

Additional context

For reference we are using the NextJS Pages router, and are specifically trying to monitor our TRPC API (as well as Temporal background workers). We're running in our own containerized setup on AWS. Any help/advice would be greatly appreciated!

[workato-integration]

https://new-relic.atlassian.net/browse/NR-345021

[gwkline]

Some additional friction I'm having:

NEW_RELIC_APP_NAME is just not being recognized (when set in both the .env file and in newrelic.js), causing the newrelic agent to fail initialization.

Especially if we want to have a newrelic app per environment, including this in the command line script is not really an option we'd like to use.

[bizob2828]

Which documentation are you referring to @gwkline? As of 12.0.0 you only need the newrelic package for Next.js instrumentation. I also recommend engaging our technical support team at https://support.newrelic.com to get assistance with your other issues you mentioned.

[gwkline]

@bizob2828 Thanks for the prompt response! Will reach out to support about the ENV issues.

Here is the (only) page explaining the intrumentation approach: https://github.com/newrelic/newrelic-node-nextjs/blob/main/docs/faqs/cloud-providers.md

Considering this is how NextJS generally recommends instrumenting apps, I am curious why this approach is not recommended. Thanks!

[jsumners-nr]

Here is the (only) page explaining the intrumentation approach

• https://github.com/newrelic/node-newrelic/blob/83fd7ee912f5548b651bfa4c1ad7d7cbbc304092/README.md#nextjs-instrumentation
• https://github.com/newrelic/node-newrelic/tree/83fd7ee912f5548b651bfa4c1ad7d7cbbc304092/documentation/nextjs/faqs

[bizob2828]

@gwkline as @jsumners-nr pointed out those pages exist in node-newrelic. The link you provided is to the archived repo for the previous Next.js instrumentation. In 12.0.0 we migrated the instrumentation into the newrelic package. I'm going to close this issue

[gwkline]

@bizob2828 Fair enough that the instrumentation is mentioned in node-newrelic.

My original problem here was that both of the NextJS examples linked are using this now-deprecated package, and with both @newrelic/next and newrelic, I was unable to get ENV vars to register properly. instrumentation.js worked out of the box, which is what lead to me asking why one is better than the other.

I still don't quite understand why the instrumentation.js approach is "worse" / not recommended, since it seems much easier to use than the NODE_OPTIONS='-r newrelic', but I will take your word on that. I did read through those FAQs prior to opening this issue. I will wait for support to get back to me in the meantime, thanks.

[bizob2828]

@gwkline the examples have been updated. check them out here. The instrumenation.js example is relying on Next.js native opentelemetry instrumentation and just sending that telemetry to New Relic via the OTLP endpoint. There is nothing related to the new relic agent in that example. We provided that as a FAQ because a lot of people were asking how to get Next.js to instrument in cloud providers. I will update the permalinks in the FAQs in node-newrelic to point to the latest

[gwkline]

Hi @bizob2828 - just wanted to follow up here since I finally got things working nicely. Here are some notes in case it might be helpful to you / anyone maintaining the docs:

• newrelic does not work with turbopack when using Next.JS
• It seems obvious in hindsight, but the ENV var issues I was seeing was from not calling dotenv/config in the start script, if that's not included newrelic has no way to pull the ENV vars from .env, even though the rest of the app might
• the ESM loader can actually be removed if you don't mind using ts-expect-error, in our case I found using the loader mangled other libs we use, so I actually had to take it out
• If you'd like to add an example of custom transaction handling, our TRPC middleware ended up looking something like this:

// @ts-expect-error
import newrelic from "newrelic"
// ...

const nrMid = middleware(async (opts) => {
  const rawInput = await opts.getRawInput()
  // in dev, we don't have newrelic, so we can ignore
  try {
    // eslint-disable-next-line @typescript-eslint/no-unsafe-call
    newrelic.setTransactionName(opts.path)
    // eslint-disable-next-line @typescript-eslint/no-unsafe-call
    newrelic.addCustomAttribute("path", opts.path)
    // eslint-disable-next-line @typescript-eslint/no-unsafe-call
    newrelic.addCustomAttribute("rawInput", JSON.stringify(rawInput))
  } catch (e) {
    // no op
  }
  return opts.next()
})

[bizob2828]

newrelic does not work with turbopack when using Next.JS

Makes sense. We don't support it.

It seems obvious in hindsight, but the ENV var issues I was seeing was from not calling dotenv/config in the start script, if that's not included newrelic has no way to pull the ENV vars from .env, even though the rest of the app might

You have to make sure you -r @dotenv/config before -r newrelic. Our example shows that

    "start": "NODE_OPTIONS='-r dotenv/config --loader newrelic/esm-loader.mjs -r newrelic' next start",

If you'd like to add an example of custom transaction handling, our TRPC middleware ended up looking something like this:

There's no reason to use our Next.js instrumentation if you're doing custom transaction naming because that's the bulk of the Next.js instrumentation. We don't want to provide an example of this because it'll confuse things.