npm-es-modules

Breakdown of 7 different ways to use ES modules with npm today.

ES Modules are the future of JavaScript, but unlike many other es@next features that developers have raced to take advantage of mainly thanks to build tools like babel, working with ES modules alongside of existing NPM modules is a lot harder to get started with.

The purpose of this tutorial is to provide a thorough set of examples for different ways you can approach writing ES modules, without losing interop with the vast library of mostly commonjs modules that exist on NPM today.

We'll start with a naive ES module in step 1 and work our way through a series of increasingly complex example approaches, all of which are intended to define the same, basic module.

Goals

Every approach must satisfy the following requirements:

• generate a valid npm module
• support the same consistent functionality
• be usable from both node.js and browser environments
• import at least one existing commonjs module from npm
• import at least one es module source file locally
• include at least one unit test

Functionality

The functionality of our example NPM module is a bit contrived, but it should touch on all the potential pain points, and trust me, there are a lot of them...

Every approach will define an NPM module with a single default export, async getImageDimensions(input), that takes in an image and returns its { width, height }.

To show how you can bundle modules with slightly different semantics for Node.js and the browser:

• the node version supports input as a string that can either be a local path, http url, or data url.
• the browser version supports input as a string URL or an HTMLImageElement.

Both versions return a Promise for { width: number, height: number }.

Approaches

1. naive - The most naive possible use of ES modules supporting our functionality. This approach is broken and provided as an example starting point.
2. babel - Uses babel to transpile all Node.js and browser source files.
3. esm-rollup - Uses esm for Node.js and babel+rollup to compile browser source files.
4. esm-webpack - Uses esm for Node.js and babel+webpack to compile browser source files.
5. rollup - Uses babel+rollup to compile all Node.js and browser source files.
6. webpack - Uses babel+webpack to compile all Node.js and browser source files.
7. typescript - Uses typescript to transpile all Node.js and browser source files.

Related

• esm - Tomorrow's ECMAScript modules today!
• babel - A compiler for writing next generation JavaScript.
• rollup - A module bundler for JavaScript.
• webpack - A bundler for javascript and friends.
• typescript - TypeScript is a typed superset of JavaScript that compiles to plain JavaScript.
• systemjs - Configurable module loader enabling dynamic ES module workflows in browsers and NodeJS.

Related Tutorials

• Native ES Modules in NodeJS: Status And Future Directions - By @giltayar
• ES modules: A cartoon deep-dive - By Lin Clark
• A Minimal Setup for Babel-based npm packages - By @rauschma
• Tomorrow’s ES Modules Today! - By @jdalton

License

MIT © Travis Fischer

Support my OSS work by following me on twitter