Using ECMAScript Modules (ESM) with Node.js

Issue

The following error is seen when starting the application with the Contrast Node agent.

UnhandledPromiseRejectionWarning: Error [ERR_REQUIRE_ESM]: Must use import to load ES Module:

Cause

ECMAScript modules are the new official standard format to package JavaScript code for reuse. ES Modules are loaded with the import module from 'module' syntax. 

Resolution

NOTE: ECMAScript instrumentation is experimental and Contrast requires at least Node version 14.15.0 for support.

When instrumenting an application that utilizes ECMAScript Modules, use the following method to start the application. This is the appropriate method for instrumenting an application that uses ESM or a combination of both ESM and CJS.

node --experimental-loader @contrast/agent/esm.mjs app-main.mjs [agent arguments] -- [app arguments]

It’s also important to note that our ESM support is in its early stages. As it stands NodeJS doesn't have the necessary internals for us to conduct proper instrumentation, our support for ESM is minimal when it comes to analyzing data flow. 

That is to say, if the code that we are instrumenting appears like:

import express from 'express';

As opposed to:

const express = require('express');

It will not be instrumented. The application should run without a crash, but findings will be limited.

ES Modules looks like it'll be tagged as stable in NodeJS 16 LTS which should unblock our efforts to instrument ES Modules.