Package Exports

esnextguardian

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (esnextguardian) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

ESNextGuardian

Load your ES6+ files if the user's environment supports it, otherwise gracefully fallback to your ES5 files.

Why?

When ESNext (i.e. ES6+) files are used natively, you gain these benefits:

It is much easier for debugging as your are debugging your source code, not compiled code
Can be faster due to:
1. Polyfills having to work around native features by going the long way, which can be very slow (e.g. () => {} vs function () {}.bind(this)
2. JavaScript engines are better able to optimise your code due to the source code maintaining the original intention better than the compiled code (e.g. const vs var)
A detailed performance comparison can be found at bevry/es6-benchmarks.

However, unless you have absolute control over the environment in which your code runs, and are only making use of ECMAScript features that the target environment supports, then you simply can't always take advantage of these benefits.

Generally, this leaves the option of compiling your ESNext code down to ES5 code, and publishing only your ES5 code for consumption — which as indicated, is harder to debug and is often slower.

The other option is to publish your ESNext code and include a runtime polyfill, which increases the runtime footprint, and makes performance at runtime slower — and may break things if the polyfill functionality conflicts or changes from package to package or version to version.

Fortunately, unless you deliberately use unstable ESNext features, then you are merely using features that are already standardized and are already making their way into modern environments, to run exactly as intended. This means your can publish your code in ESNext today with expectations of it working in the environments of the future.

We can utilise this feature of ESNext to our advantage, by publishing both the ESNext code, as well as our compiled fallback ES5 code, we can publish code that will have many benefits in environments that supports it, and fallback to harder to debug slower code on environments that don't support the best. The best of both worlds. This is what ESNextGuardian makes easy for you.

Usage

If you haven't already got setup with ES6+, you can do so by:
1. Installing Babel as a development dependency:
```
npm install --save-dev babel
```
2. Use this command to compile your ES6+ files (inside an esnext directory) to ES5 files (inside a es5 directory):
```
./node_modules/.bin/babel esnext --out-dir es5
```
  Optional: If you would like that command to run with npm run-script compile instead (which is a bit more streamlined), you can do so by adding it to your package.json file under scripts then compile like so:
```
{
    "scripts": {
        "compile": "./node_modules/.bin/babel esnext --out-dir es5"
    }
}
```
Install and add esnextguardian to your project's dependencies:
```
npm install --save esnextguardian
```

Create an esnextguardian.js file in the root of your project, containing the following:

 module.exports = require('esnextguardian')(
   require('path').join(__dirname, 'esnext', 'lib', 'index.js'),
   require('path').join(__dirname, 'es5', 'lib', 'index.js')
 )

Customize the paths to your desired ESNext and ES5 main files.

Make the following changes to your package.json file:
1. Specify the main property to point to your esnextguardian.js file, like so:
```
{
    "main": "./esnextguardian.js"
}
```
2. Optional: If you want to force browser compilers to online include the ES5 copy of your code, specify the browser property to point to your ES5 file, like so:
```
{
    "browser": "./es5/lib/index.js"
}
```
All done, you may now test and publish your package.
Optional: If you don't want your git repository polluted with your ES5 compiled files, add your ES5 files to your .gitignore file, like so:
```
# Build Files
es5/
```