• Log inStart now

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.

Caution

Node.js APM agent support for instrumentation in ES module applications is experimental. The agent is reliant on an experimental Node.js feature in order to register instrumentation. Breaking changes can occur until the Node.js API for ES module loaders is stable.

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.

Important

The minimum supported version of Node.js when using the Node.js APM agent in ES module applications is v16.12.0.

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 in your application's invocation. You can add the loader to your application by using the Node.js --experimental-loader CLI argument.

bash
$
node --experimental-loader newrelic/esm-loader.mjs 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

Copyright © 2023 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.