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.
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.
Why use Editions?
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.
Alternative ApproachesDefining Editions
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.
How do I define an Edition?
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 editiona
directory
field for where the edition is locateda
entry
field for the default file inside thedirectory
to be loadedan optional
tags
field for common keywords to describe the edition that tooling can utilise
You can find the full technical specification here:
SpecificationExample Editions Definition
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:
Automatic Creation of Editions
Tools like Boundation can automatically create for you the editions definition as well as the editions themselves.
Consuming Editions
Editions can be consumed in multiple ways, here are the options:
A Specified Edition
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:
Best Edition for the Environment
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.index.jsSet the
package.json
propertymain
to point to theindex.js
file above, instead of a specfic edition.package.json
Custom Entry Points
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 bestbin.js
script from our available compatible editions.bin.jsSet the
bin
property in ourpackage.json
file to point to the rootbin.js
file we just created.package.json
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 besttest.js
script from our available compatible editions.bin.jsSet the
scripts.test
property in ourpackage.json
file to point to the roottest.js
file we just created.package.json
Manually Require a Specific Edition
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.
Browser Edition
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:
EcosystemDocumenting Editions
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 -->
.
Automatic Editions Rendering without the Editions Autoloader
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
Automatic Editions Documentation with the Editions Autoloader
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
Last updated