Node.js opened the door for developers to build performant web servers using JavaScript.
The explosion of CommonJS modules which followed, created a massive new ecosystem. Building a typical website today involves hundreds, if not thousands, of modules.
To publish a module, you set module.exports
in your code, create a package.json
file, and run npm publish
.
To consume a module, you add a dependency to your package.json
file, run npm install
, and call require('module-name')
from your code.
Modules can depend on other modules.
Npm moves module files between a central registry and the machines running Node.js.
In 2015, import
and export
statements were added to JavaScript. ESM module loading is now a built-in feature of all major browsers (sorry IE.)
ESM removes the need for package.json files, and uses URLs instead of npm module names -- but it does not preclude those from being used with ESM, say in a Node.js context.
To publish an ESM module, use export
in your code, and make the file fetchable by URL.
To consume an ESM module, use import { ... } from URL
. See MDN for more details.
Using import
instead of require()
allows ESM modules to be loaded independently, without running the code where they are used. A variant of the import
statement, is the dynamic import() function. This allows for modules to be loaded asynchronously at run-time.
ESM is the basis for exciting new developer tools like Snowpack and Vite.
Even before ESM, developers could use npm modules in front-end code. Tools like browserify or webpack bundle modules into a single script file, loadable by browsers.
On the server side, it has taken Node.js a few years to arrive at ESM support. Unfortunately, the 2 standards are not fully interoperable.
Despite everyone's best intentions, the Node.js docs are unclear about what to do. For a deeper explanation, I recommend this article by Dan Fabulich.
Here is a summary of some interop scenarios:
Node's inability to require() ESM modules prevents simple upgrades from CommonJS to ESM.
Publishing dual ESM-CJS packages is messy because it involves wrapping CommonJS modules in ESM. Writing a module using ESM and then wrapping it for CommonJS is not possible.
Fortunately, dynamic import() provides an alternative.
Dynamic import() works from the default Node.js context as well as from an ESM context. You can even import() CJS modules. The only gotcha is that it returns a promise, so it is not a drop-in replacement for require().
Here is an example showing require() and import() together.
I published shortscale v1 as CommonJS. For v2 and later the module is only available as ESM. This means that later releases can no longer be loaded using Node.js require().
This fastify server loads both module versions from a CJS context.
// minimal fastify server based on:
// https://www.fastify.io/docs/latest/Getting-Started/#your-first-server
const fastify = require('fastify')({ logger: true });
fastify.register(async (fastify) => {
let shortscale_v1 = require('shortscale-v1');
let shortscale_v4 = (await import('shortscale-v4')).default;
// e.g. http://localhost:3000/shortscale-v1?n=47
fastify.get('/shortscale-v1', function (req, res) {
let num = Number(req.query.n);
let str = '' + shortscale_v1(num);
res.send({num, str});
});
// e.g. http://localhost:3000/shortscale-v4?n=47
fastify.get('/shortscale-v4', function (req, res) {
let num = Number(req.query.n);
let str = '' + shortscale_v4(num);
res.send({num, str});
});
});
// Run the server!
fastify.listen(3000, function (err, address) {
if (err) {
fastify.log.error(err);
process.exit(1);
}
fastify.log.info(`server listening on ${address}`);
});
For this demo, package.json
installs both versions of shortscale.
{
"name": "demo-fastify-esm",
"version": "1.0.0",
"description": "Demonstrate ESM dynamic import from non-ESM server",
"main": "server.js",
"scripts": {
"start": "node server.js"
},
"author": "Jürgen Leschner",
"license": "MIT",
"dependencies": {
"fastify": "^3.11.0",
"shortscale-v1": "npm:shortscale@^1.1.0",
"shortscale-v4": "npm:shortscale@^4.0.0"
},
"repository": {
"type": "git",
"url": "https://github.com/jldec/demo-fastify-esm"
}
}
I plan to migrate my modules to ESM. Other module authors are too.
📦📦
To leave a comment
please visit dev.to/jldec