Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/bevry-archive/esnextguardian

Superseded by the editions package: https://editions.bevry.me
https://github.com/bevry-archive/esnextguardian

client-side nodejs nodejs-modules

Last synced: about 10 hours ago
JSON representation

Superseded by the editions package: https://editions.bevry.me

Host: GitHub
URL: https://github.com/bevry-archive/esnextguardian
Owner: bevry-archive
License: other
Created: 2015-09-18T02:46:30.000Z (about 9 years ago)
Default Branch: master
Last Pushed: 2016-05-02T05:01:05.000Z (over 8 years ago)
Last Synced: 2024-04-08T15:41:51.391Z (7 months ago)
Topics: client-side, nodejs, nodejs-modules
Language: JavaScript
Homepage:
Size: 38.1 KB
Stars: 7
Watchers: 1
Forks: 1
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: HISTORY.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md

Awesome Lists containing this project

README

ESNextGuardian

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

**UPDATE:** [Editions](https://github.com/bevry/editions) is the spiritual successor of ESNextGuardian - while they are not the same, they mostly address the same use case.

## 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](https://github.com/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](https://babeljs.io) as a development dependency:

``` shell
npm install --save-dev babel-cli
```

1. [Configure](http://babeljs.io/docs/plugins/preset-es2015/) Babel to compile ESNext to ES5:

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

1. Use this command to compile your ESNext files (inside an `esnext` directory) to ES5 files (inside a `es5` directory):

``` shell
./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:

``` json
{
"scripts": {
"compile": "babel esnext --out-dir es5"
}
}
```

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

``` shell
npm install --save esnextguardian
```

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

``` javascript
// 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.

1. Make the following changes to your `package.json` file:

``` json
{
"main": "./esnextguardian.js",
"browser": "./es5/lib/index.js",
"jsnext:main": "./esnext/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](http://browserify.org/) (a CommonJS compiler that uses the [`browser` field](https://github.com/substack/node-browserify#browser-field))
- [rollup](http://rollupjs.org) (a CommonJS and ESNext compiler that uses the [`jsnext:main` field](https://github.com/rollup/rollup/wiki/jsnext:main))
- [jspm](http://jspm.io) (an ESNext package manager that uses the [`jspm.main` field](https://github.com/jspm/registry/wiki/Configuring-Packages-for-jspm#prefixing-configuration))
- jspm uses the ES5 Script as ESNext support in jspm has not been released yet, [details here](https://github.com/bevry/domain-browser/pull/7#issuecomment-160814333)

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

### Notes

#### Modules

Node.js [does not support](https://twitter.com/balupton/status/671519915795345410) [ECMAScript Modules](https://babeljs.io/docs/learn-es2015/#modules) so if you want ESNextGuardian to be of any value, be sure to use [Node.js (CommonJS) Modules](https://nodejs.org/api/modules.html) exclusively in your modules.

If you use [ESLint](http://eslint.org) you can set `ecmaFeatures.modules` to `false` in your [ESLint configuration](http://eslint.org/docs/user-guide/configuring) to help enforce this.

#### Gitignore

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

#### Flags

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