search

hypercore-protocol / community

Public discussions for Hypercore Protocol
16 stars 1 forks source link

ES Modules for documentation / distributed artifacts #5

Open cdata opened 4 years ago

cdata commented 4 years ago

This is a follow-up issue related to discussion in https://github.com/hypercore-protocol/hypercore-protocol/issues/53 and in the downstream Dat SDK project https://github.com/datproject/sdk/issues/55

TL;DR Please consider distributing this module (and others in the Hypercore ecosystem) as an ES Module, and prefer documentation that demonstrates how to use it as an ES Module.

A relevant note from discussion in https://github.com/hypercore-protocol/hypercore-protocol/issues/53 is copied here for your convenience:

Although it is technically true that ESM is still labeled experimental in the current Node.js (LTS), the following points are worthy of consideration as well:

  • In the latest release of Node v12 (LTS), ESM support no longer requires a flag
  • ESM have been available in stable releases of all major browsers for a few years now

The rationale from the downstream issue https://github.com/datproject/sdk/issues/55 is copy/pasted here for your convenience:

The frontier of the JavaScript library-building community is moving towards expressing distributed libraries as ES Modules. Tools like Rollup.js and Node.js¹ are creating cowpaths for a package ecosystem where modules can be more easily/consistently imported in multiple environments by adopting the standard JavaScript module syntax.

On the one hand, I'm sure that a full-conversion to ES Modules would be a lot of work, and is likely not feasible given the sheer number of dependencies involved. On the other hand, it seems like it would be feasible to distribute an artifact that uses ES Modules so that others can consume the SDK that way, and to reflect that mode of usage in documentation.

In the long run, preferring ES Module-based packages will make it easier for dependent projects to apply optimizations such as sharing dependency packages with the SDK, tree shaking and code splitting. These optimizations may be possible today, but in order to apply them effectively we would need a comparatively intimate knowledge of the DAT SDK's dependency graph and all the errata to correctly bundle it.

The DAT SDK is a massive body of JavaScript. The more of it that can be consumed in a standard, consistent module format, the easier it will be to accept the byte cost it brings as a dependency.

Thank you for your consideration, and I look forward to hearing your thoughts on this issue.

¹ Node v12.17.0 "--experimental-modules flag is no longer necessary to use ECMAScript modules (ESM)"

And one suggestion for incrementally moving packages in this direction was also offered:

One approach could be to continue publishing as you are today, but also take advantage of the "exports" field in package.json to publish CommonJS and ESM in a way that advertises a different entrypoint depending on the context (legacy Node.js, modern Node.js or bundling tool).

mafintosh commented 4 years ago

Thanks @cdata Will just put in the points from the other issue: