Packages only include production source code and a few mandatory files (included by default). The safe way to handle it is via package.json's files key which looks something like this:
{
"files": [
"/lib/**/*.js",
"!/lib/**/*.test.js",
"/lib/**/*.json",
"/lib/**/*.svg"
],
}Update 2020-01-13: Mocha released experimental support in [email protected]
Update 2019-10-22: this 2ality post explains the possibilities of publishing hybrid NPM packages. Library support will have to be tested.
TLDR; no ESM.
There are many ways to interpret ES Modules, e.g. esm, Node's native experimental support (1, 2, 3) or webpack (1, 2). The common convention for declaring them is to use the .mjs extension for ESM files and .js (or .cjs) for CommonJS files.
Shipping backward compatible ESM packages could happen as:
- shipping both
.mjsand.jsfiles and letting the interpreters chose - shipping only
.mjsfiles and forcing the interpreters to transpile when needed
The question "Is it safe to release ESM packages?" boils down to:
- Can interpreters handle ESM files?
- Can interpreters fall back to CommonJS files when needed?
TLDR; sadly no and no.
- Node.js plans to officially support ESM in October 2019
- developing support in many libraries will only start after Node's proposal is no longer subject to change
- esm package's support doesn't align with Node's which causes issues
- "Builtin require cannot sideload .mjs files." https://github.com/standard-things/esm#loading, standard-things/esm#498 (comment)
- "The .mjs file extension should not be the thing developers reach for if they want interop or ease of use. It's available since it's in --experimental-modules but since it's not fully baked I can't commit to any enhancements to it." standard-things/esm#498 (comment)
- mocha doesn't have native support for
.mjsfiles - Many high-profile projects had issues with
.mjsfiles:
- Node's proposed way of automatically selecting the right files when the extension is omitted is broken with the release of v12. They went as far as to request: "Please do not publish any ES module packages intended for use by Node.js until this is resolved."
- Transpiling dependencies is painful and unreliable