Serverless is incompatible with server-side modules that use `esm`

Because the esm pkg is not intended to be used with webpack, it doesn’t work quite right with target: 'serverless'.

More details can be found in the original issue filed with now-cli: https://github.com/zeit/now-cli/issues/2569.

Despite the advise esm gives to prefer the module key, this is not actually feasible or a proper solution.

This mainly boils down to two reasons, broadly speaking:

1. The module field is largely a browser field, not a Node.js field.
2. Many packages are published with a CJS (main) variant that does not use the default key, meaning the non-standard switch to ESM breaks packages that work in Node.

The only viable options is to transform source code to remove esm.

[Timer]

browser typically indicates a UMD build or similar, not a bundler-friendly build. That’s why browser code is under the module key, because it spawned from webpack (first-and-foremost, a front-end bundler).

Ultimately, we have too few field choices to work with here.

For maximum ecosystem compatibility, in my experience, you must:

1. Avoid using the esm package for things intended to be used in browser and Node. This package works great for Node-only packages.
2. Ship ES Modules code, compiled down to ES5, under the modules field
3. Ship CommonJS code, compiled down to oldest non-EOL Node version, under the main field.
4. ☝️ both of these bundles should be isomorphic, working in a Node and Browser environment if you need them to (typeof window or typeof process, never process.browser).

However, more projects are moving towards compiling ./node_modules/ which allow you to ship ES.Latest under the module key. Next.js will do this soon. Some other parts of the ecosystem still need to catch up, so this isn’t generally safe yet. Do note, compiling other users code is not a safe behavior, but works in most cases.

The code shipped under the main key still should be compiled down to the oldest-non-EOL Node version.

TBH, for your specific case, I would:

1. Publish esmodules code under module key
2. Have a main field with the value of index (note no extension), this allows users to resolve .mjs first if they desire in their bundler, otherwise gives .js w/ CJS
3. Include a index.mjs that re-exports the module key’s entry point (or, preferably, skip this all together since ESM in Node.js isn’t a real thing)
4. Include a index.js that contains compiled commonjs code

☝️ unfortunately there’s no esm in this picture since your code is designed to be used in browser and server.

Whilst this will actually be solved in Next.js soon (and you can use your current setup, with esm as-is), you may find other users / tools having to customize their setup to accommodate it.

---

Edit: Just want to add/reiterate:

The above suggestion is an opinion based on my experiencing maintaining two popular DX Toolboxes. There is no right or wrong answer because none of these fields are based on standards.

These practices also do not reflect the direction the ecosystem is potentially heading in the future, because they’re concerned with present-day maximum compatibility.

As an anecdote, you’ll see Node 12 uses a completely different behavior and that users are beginning to ask for ES.Latest to be published.

[Timer]

No @ericelliott, because they end up being bundled by webpack which converts them into commonjs.