Using the Node.js agent in an ESM application

If you use ESM to manage code in your Node.js applications, you can now monitor those applications using the Node.js agent.

Overview

Prior to v12.0.0, Node.js only officially supported managing code using CommonJS modules. CommonJS modules use module.exports and require() statements to manage code as in this example:

'use strict'

const bar = require('./bar')

function echoBar() {
  console.log('this is bar:', bar)
}

module.exports = {
  echoBar
}

Since Node.js v12.0.0, support for ECMAScript modules (ES modules/"ESM") has been added.

Instead of require() and module.exports, ESM uses import and export statements like this:

'use strict'

import bar from './bar.js'

export function echoBar() {
  console.log('this is bar:', bar)
}

ESM is the official ECMAScript standard for code management and is the standard way browsers and other JS runtimes manage packages. In order to support the evolving Node.js ecosystem, both now and in the future, the agent supports instrumenting applications written using ESM, as of version 9.1.0 of the agent. The Node.js APM agent also continues to support CommonJS applications.

Agent setup

In order for the agent to successfully instrument an ESM application, you will need to first install the Node.js agent, as described in the Installation documentation. Once your agent is installed, continue with the configurations in the sections below.

Configuration

If your application uses a configuration file to configure the agent, you will need to update the configuration file's extension to be .cjs instead of .js.

The agent is written as a CommonJS module; it uses require() to read the configuration file in at startup. By changing the file extension, we explicitly label the agent's configuration file as a CommonJS module, allowing the agent to load it successfully.

If you don't update the file extension, you may see the following error during agent startup:

New Relic for Node.js is disabled due to an error:
Error [ERR_REQUIRE_ESM]: require() of ESM /path/to/your/application/newrelic.js from /path/to/your/application/node_modules/newrelic/lib/config/index.js not supported.

Add the ESM loader

In order for the agent to properly apply instrumentation within the ESM ecosystem, you must include the agent's ESM loader along with the agent in your application's invocation. You can add the loader to your application by using the Node.js --import CLI argument.

$
node --import newrelic/esm-loader.mjs -r newrelic your-program.js

Custom instrumentation

The Node.js APM agent supports adding custom instrumentation to your ESM applications. You can create instrumentation in ESM applications using most of the instrumentation registration methods on the API. Due to the nature of ESM imports, the agent doesn't support newrelic.instrumentLoadedModule. ESM bindings aren't assignable, which prevents the agent from replacing a module's exported members with instrumentation after the module has loaded.

To see a demonstration of how to use the custom instrumentation API in an ESM application, check out our example in GitHub.

Learn More

• Node.js ESM documentation
• Node.js Packaging documentation
• ECMAScript Standards documentation
• Demo ESM Application