transitive-bullshit / npm-es-modules

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

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

npm-es-modules's Issues

Discussing esm + best practices

This issue is intended to discuss @jdalton's PR #1 in more depth, with the goal of unifying a set of best practices across the other example modules.

One thing I'll likely do in the near future is create a sibling repo that doesn't create different browser and node entrypoints, because that's complicated these examples quite a bit, and I feel like it's not necessary for the majority use case.

@jdalton a few notes on your PR (merged):

0. Completely agree with having files end in js instead of mjs. Trying to get existing tools to play nicely with mjs is currently a serious pain point.

1. Having index.js instead of main.js is reasonable, in terms of interop with existing developer expectations, but then renaming the ES module entrypoint main.js instead of module.js seems really weird and backwards to me, so I reverted this part of the change.

2. I was surprised to find that the webpack config wouldn't load because of it's ES module syntax after the PR, but once I moved the example to its own, isolated directory, everything worked fine. It seems there's some oddness around different versions of ava being included in different workspaces within the same lerna monorepo. To get around this, I just ended up upgrading all uses of ava to the latest alpha.

3. I'm going through now and applying as many of your suggestions to the other example modules as possible.

Tsconfig files are identical

Maybe I overlooked something but apart from outDir both files tsconfig.json and tsconfig.esm.json are identical. Are you sure that is correct?