---
title: Using the Node.js agent in an ESM application
tags:
  - Agents
  - Nodejs agent
  - ESM
  - ES modules
  - Experimental
metaDescription: How to install and configure your Node.js APM agent for an application that uses ESM.
freshnessValidatedDate: never
---

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

<Callout variant="caution">
  Node.js APM agent support for instrumentation in [ESM](https://nodejs.org/api/esm.html) 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 [ESM loaders](https://nodejs.org/api/esm.html#loaders) is stable.
</Callout>

## Overview [#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:

```js
'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:

```js
'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.

<Callout variant="important">
  The minimum supported version of Node.js when using the Node.js APM agent in ESM applications is v16.12.0.
</Callout>

## Agent setup [#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](/docs/apm/agents/nodejs-agent/installation-configuration/install-nodejs-agent). Once your agent is installed, continue with the configurations in the sections below.

### Configuration [#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 [#add-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](https://nodejs.org/api/cli.html#--importmodule).

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

## Custom instrumentation [#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](https://newrelic.github.io/node-newrelic/API.html#instrument).
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](https://github.com/newrelic/newrelic-node-examples/blob/4284ee7eab69708238db0a44f97ff7e839e165cf/esm-app/custom-instrumentation/index.js) in GitHub.

## Learn More [#learn-more]

* [Node.js ESM documentation](https://nodejs.org/api/esm.html#introduction)
* [Node.js Packaging documentation](https://nodejs.org/api/packages.html#introduction)
* [ECMAScript Standards documentation](https://tc39.es/ecma262/#sec-modules)
* [Demo ESM Application](https://github.com/newrelic/newrelic-node-examples/tree/main/esm-app)