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:

1. It is much easier for debugging as your are debugging your source code, not compiled code

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

1. If you haven't already got setup with ES6+, you can do so by:

   1. Install Babel as a development dependency:

      npm install --save-dev babel-cli

   2. Configure Babel to compile ESNext to ES5:

      npm install --save-dev babel-preset-es2015
      wget -N https://raw.githubusercontent.com/bevry/base/master/.babelrc

   3. Use this command to compile your ESNext 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"
          }
      }

2. Install and add ESNextGuardian to your project's dependencies:

   npm install --save esnextguardian

3. Create an esnextguardian.js file in the root of your project, containing the following, customising the paths to your desired ESNext and ES5 main files.

   // 2015 December 8
   // https://github.com/bevry/esnextguardian
   'use strict'
   module.exports = require('esnextguardian')(
       require('path').join(__dirname, 'esnext', 'lib', 'index.js'),
       require('path').join(__dirname, 'es5', 'lib', 'index.js'),
       require
   )

   We pass require as the 3rd argument to ensure that the require setup/configuration/environment remains the same as the module calling ESNextGuardian, it can differ between modules.

   We use require('path').join with __dirname to ensure that debugging messages and stack traces are indicative of the module calling ESNextGuardian, as the relative paths alone do not provide enough to be useful for those use cases.

4. Make the following changes to your package.json file:

   {
       "main": "./esnextguardian.js",
       "browser": "./es5/lib/index.js",
       "jspm": {
           "main": "./es5/lib/index.js"
       }
   }

   This will use:

   • The ESNextGuardian script by default for cross-enviroment compatibility
   • The ES5 Script for:
     • browserify (a CommonJS compiler that uses the browser field)
     • jspm (an ES6 package manager that uses the jspm.main field)
       • jspm uses the ES5 Script as ESNext support in jspm has not been released yet, details here

5. All done, you may now test and publish your package.

Notes:

• Node.js does not support ECMAScript Modules so if you want ESNextGuardian to be of any value, be sure to use Node.js (CommonJS) Modules exclusively in your modules.

  If you use ESLint you can set ecmaFeatures.modules to false in your ESLint configuration to help enforce this.

• 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/
  

• The following environment boolean flags are available:

  • DEBUG_ESNEXTGUARDIAN when true will output relevant debug information regarding (it is recommended you enable this for your development environments):

    • If the ESNext script fails to load, the error message as to why will be outputted
    • If relative paths were provided to ESNextGuardian a non-fatal warning will be outputted
    • If the require argument was not provided to ESNextGuardian, a non-fatal warning will be outputted

  • REQUIRE_ESNEXT when true will only attempt to load the ESNext script

  • REQUIRE_ES5 when true will only attempt to load the ES5 script

History

Discover the release history by heading on over to the HISTORY.md file.

Contribute

Discover how you can contribute by heading on over to the CONTRIBUTING.md file.

Backers

Maintainers

These amazing people are maintaining this project:

• Benjamin Lupton — view contributions

Sponsors

No sponsors yet! Will you be the first?

Contributors

These amazing people have contributed code to this project:

• Benjamin Lupton — view contributions

Discover how you can contribute by heading on over to the CONTRIBUTING.md file.

License

Unless stated otherwise all works are:

• Copyright © 2015+ Bevry Pty Ltd

and licensed under:

• MIT License