RFC: ESM Dependency Requirements Format

[vovacodes]

As ESM libraries embrace the usage of "bare" module specifiers the very logical problem arises - how do they specify and communicate the version and/or source requirements to the library users?

For the libraries that are published to npm the package.json's "dependecies" field serves that purpose. But what should be used for the other sources:

• github.com (also handled in the package.json spec)
• deno.land/x/
• framer.com/m/
• CodeSandbox CDN, etc

Two Types of Specifies

• rigid, can't be deduplicated, should probably just be URLs
• flexible, can be deduplicated
  • how can tooling access the requirements data? In an HTTP header? a "conventional" endpoint derivable from the module URL? something else?
  • how can tooling access information about available versions from the source? We need some protocol or convention for that.
  • can the specifier be a URL itself so deduplication is an progressive enhancement?

Proposed Requirements Formats

npm packages

npm packages can be referred to by using a slightly modified version of the standard npm query string that adds support for subpaths:

"react-dom": "react-dom@^17.0.2"
// "react-dom/server": "react-dom@^17.0.2/server"

URLs

Individual modules served from arbitrary URLs can include a semver part at a certain position, e.g. at the end like it's implemented by Framer CDN:

"#framer/input": "https://framer.com/m/framer/Input.js@^0.26.0"

Packages can use a slightly different position for version, e.g. how deno/x/ does it:

"#deno/x/oak": "https://deno.land/x/[email protected]/mod.ts"

The source CDNs can communicate the available versions using a different URL that's deriveable from the module URL, e.g.:

https://framer.com/m/framer/[email protected]/versions
https://deno.land/x/oak/mod.ts/versions

The areas for comments:

• How should a module served from a URL communicate its dependency requirements;
• How can a tool discover the available versions given a module/package URL;

[guybedford]

Per discussion, there seemed to be two major questions here:

• How to standardize version resolution?
• How to standardize URL parsing into a registry identifier, package name and version.

For eg a /versions URL convention, getting buy-in from existing CDNs would be important.

URL parsing seems like it might be doable with existing version and package name conventions if then treating unknown domains as effectively discovered registries based on the URL host name as the registry identifier.

[JayaKrishnaNamburu]

As we discussed on how jspm/providers can help in resolving these dependencies and generate importmaps. I would also be interested, if there can be a generic solution.
That any esm serving CDN's can adopt as a spec or the only proper way to handle this via importmaps. In a context where npm is not going to be the source of truth.

How should a module served from a URL communicate it's dependency requirements.

• So, let's say i made a module [email protected] and pushed to jspm server directly. How the module is going to be stored?
• Should the module be packed together something like npm pack which holds the module and the versions file.
• Should the versions file more or less looks like importmap and behaves as such and served back to the users along with the module back when requested.
• If the module is requested in future. Will the CDN serves with importmaps (versions file here) ?
• Should the cdn service consider, ahead of time compilation. Like how it works with npm packages now. As, all npm packages are compiled to esm and saved.
• Which in this case, a package of module file + versions file are compiled together and all the imports are resolved. And from next request just serve the module as usual.
• Or even when publishing to the CDN registry, the versions map can be passed via headers. And so the compilation can be taken care of.