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.

Example 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:

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

}

}

]

}

Automatic Creation of Editions

Tools like Boundation can automatically create for you the editions definition as well as the editions themselves.

Set the package.json property main to point to the index.js file above, instead of a specfic edition.

package.json

{

"main":"index.js"

}

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 best bin.js script from our available compatible editions.

Documenting 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 --> .