Using the Node.js agent in an ES module application

If you use ES modules 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, ES modules use import and export statements like this:

'use strict'

import bar from './bar.js'

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

ES modules are the official ECMAScript standard for code management and are 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 ES modules, 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 ES modules 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 ES module /path/to/your/application/newrelic.js from /path/to/your/application/node_modules/newrelic/lib/config/index.js not supported.

Add the ES module loader

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

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

Custom instrumentation

The Node.js APM agent supports adding custom instrumentation to your ES module applications. You can create instrumentation in ES module applications using most of the instrumentation registration methods on the API. Due to the nature of ES module imports, we are unable to support newrelic.instrumentLoadedModule. ES module bindings are not assignable, which prevent the agent from replacing a module's exported members with instrumentation after the module has been loaded.

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

Learn More

• Node.js ES module documentation
• Node.js Packaging documentation
• ECMAScript Standards documentation
• Demo ES Module Application