Overview
Editions are the best way to produce and consume the JavaScript packages you care about. With Editions you can produce packages beautifully, and consume packages perfectly.
Last updated
Editions are the best way to produce and consume the JavaScript packages you care about. With Editions you can produce packages beautifully, and consume packages perfectly.
Last updated
Editions is a backwards compatible standard for describing the ways in which your project has been produced to accelerate manual consumption, as well as automatic consumption through Ecosystem Tooling.
JavaScript production and consumption has gotten difficult over the years.
Production use to be as easy as publishing your source code, which worked across all environments, with a few minor tweaks. Consumption was as easy as including the package, and you are done.
However, these days, code may be run anywhere, in all sorts of browsers, desktop environments, and devices, of varying capabilities, not always known by the producer. JavaScript has also evolved, incorporating a lot of modern features that save developers time, but not supported across all possible environments - either requiring abstinence of time saving features, or eliminating environment support, or compilation on either the producer or consumer side - this is all complex and difficult to manage.
Editions comes in to solve this problem, elegantly, and in a standardised way, that works with current environments and development setups. Producers are able to produce their packages in their ideal configurations, then publish the package with multiple editions for the consumers to consume at their digression. Consumers are made aware of this through automated README updates, and can select the exact edition that meets their exact needs - and by default, the best edition for the environment can be automatically loaded. All the complexity of modern JavaScript publishing is solved, for the consumer and publisher.
If you wish to delve further, refer to the Alternative Approaches document for a complete understanding of the problem space and why editions is a superior solution in it.
An edition is each variation of your code. Usually this comes in the form of your source edition, as well as compiled editions for each environment you wish to support.
Practically, editions are specified in descending order of preference in the editions
field of your package.json
, with each edition being composed of the following fields:
a description
field to describe the edition
a directory
field for where the edition is located
a entry
field for the default file inside the directory
to be loaded
an optional tags
field for common keywords to describe the edition that tooling can utilise
You can find the full technical specification here:
For a project that has a source edition written in ESNext using require('some-package')
syntax, with a compiled edition for the default browsers, as well as a compiled edition for older node versions, then a compatible editions definition for it would look like so:
Tools like Boundation can automatically create for you the editions definition as well as the editions themselves.
Editions can be consumed in multiple ways, here are the options:
For producers who only want one edition to be used by default, they can specify the default edition to be loaded via the standard main
property of the package.json
file:
For producers who want consumers to automatically load the best edition for the consumers particular environment, you can make use of the Editions Autoloader package.
Inside your project, install the Editions Autoloader package via npm install --save editions
Create a root index.js
file that uses the Editions Autoloader to load the best edition from our available compatible editions.
Set the package.json
property main
to point to the index.js
file above, instead of a specfic edition.
For binary executables or testing, we then we would want to specify a non-default entry to load for the editions. We can do this by passing the custom entry point as an extra argument to the requirePackage
function.
To specify a bin.js
custom entry, then we would perform the following.
Create a root bin.js
file that uses the Editions Autoloader to load the best bin.js
script from our available compatible editions.
Set the bin
property in our package.json
file to point to the root bin.js
file we just created.
To specify a test.js
custom entry, then we would perform the following.
Create a root test.js
file that uses the Editions Autoloader to load the best test.js
script from our available compatible editions.
Set the scripts.test
property in our package.json
file to point to the root test.js
file we just created.
For consumers who are informed about the particular editions that an editioned package offers, they can opt into a non-standard edition by specifying it manually in their consumption.
For our Example Editions Definition from earlier, we would define the browser
field in our package.json
like so:
This usage of the browser
field tells most tools like Browserify, WebPack, and Rollup to specifically use the edition that we precompiled for the browsers we target for.
You can find more information about the browser
field and its equivalents here:
You can find tooling that already has builtin support for the Editions specification here:
If producers wish to inform consumers of the editions they provide, which is not necessary for consumption, but useful to the consumer, then producers can utilise Projectz to inject the appropriate editions information into your README.md
file via the HTML comment <!-- INSTALL -->
.
If we partner our Example Editions Definition from earlier with the following package.json
fields:
This will have Projectz turn the <!-- INSTALL -->
comment in our README.md
file into the following rendered output:
require('project')
aliasesrequire('project/edition-node-0.8')
require('project/source')
is ESNext source code with require for modules
require('project/edition-browsers')
is ESNext compiled for browsers with require for modules
require('project/edition-node-0.8')
is ESNext compiled for Node.js >=0.8 with require for modules
If we partner our Example Editions Definition from earlier to make use of the Editions Autoloader, then Projectz will turn the <!-- INSTALL -->
comment in our README.md
file into the following rendered output:
require('project')
aliasesrequire('project/index.js')
which uses the Editions Autoloader to automatically select the correct edition for the consumers environment
require('project/source')
is ESNext source code with require for modules
require('project/edition-browsers')
is ESNext compiled for browsers with require for modules
require('project/edition-node-0.8')
is ESNext compiled for Node.js >=0.8 with require for modules