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.
Watch the 2016 introductory talk to the Editions ecosystem.
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 thedirectory
to be loaded
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:package.json
{
"editions": [
{
"description": "esnext source code with require for modules",
"directory": "source",
"entry": "index.js",
"tags": [
"javascript",
"esnext",
"require"
],
"engines": {
"node": ">=6",
"browsers": false
}
},
{
"description": "esnext compiled for browsers with require for modules",
"directory": "edition-browsers",
"entry": "index.js",
"tags": [
"javascript",
"require"
],
"engines": {
"node": false,
"browsers": "defaults"
}
},
{
"description": "esnext compiled for node.js >=0.8 with require for modules",
"directory": "edition-node-0.8",
"entry": "index.js",
"tags": [
"javascript",
"require"
],
"engines": {
"node": ">=0.8",
"browsers": false
}
}
]
}
Tools like Boundation can automatically create for you the editions definition as well as the editions themselves.

GitHub - bevry/boundation: Automatic scaffolding and upgrading of your JavaScript ecosystem projects using Bevry's best practices
GitHub
Automatically create your Editions with Boundation
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:package.json
{
"main": "edition-node-0.8/index.js"
}
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.
- 1.Inside your project, install the Editions Autoloader package via
npm install --save editions
- 2.Create a root
index.js
file that uses the Editions Autoloader to load the best edition from our available compatible editions.index.js'use strict'/** @type {typeof import("./source/index.js") } */module.exports = require('editions').requirePackage(__dirname, require) - 3.Set the
package.json
propertymain
to point to theindex.js
file above, instead of a specfic edition.package.json{"main": "index.js"}
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.- 1.Create a root
bin.js
file that uses the Editions Autoloader to load the bestbin.js
script from our available compatible editions.bin.js#!/usr/bin/env node'use strict'/** @type {typeof import("./source/bin.js") } */module.exports = require('editions').requirePackage(__dirname, require, 'bin.js') - 2.Set the
bin
property in ourpackage.json
file to point to the rootbin.js
file we just created.package.json{"bin": "bin.js"}
To specify a
test.js
custom entry, then we would perform the following.- 1.Create a root
test.js
file that uses the Editions Autoloader to load the besttest.js
script from our available compatible editions.bin.js'use strict'/** @type {typeof import("./source/test.js") } */module.exports = require('editions').requirePackage(__dirname, require, 'test.js') - 2.Set the
scripts.test
property in ourpackage.json
file to point to the roottest.js
file we just created.package.json{"scripts": {"test": "node ./test.js"}}
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.
// using require
require('a-editioned-package/a-custom-edition/')
// using import
import blah from 'a-editioned-package/a-custom-edition/'
For our Example Editions Definition from earlier, we would define the
browser
field in our package.json
like so:package.json
{
"browser": "edition-browsers/index.js"
}
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 -->
.package.json
{
"main": "editions-node-0.8/index.js"
}
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')
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
Last modified 4yr ago