js-openstack-lib/doc/source/specs/es2015.rst

Copyright 2016 Hewlett Packard Development Corporation, L.P.

This work is licensed under a Creative Commons Attribution 3.0
Unported License.
http://creativecommons.org/licenses/by/3.0/legalcode

Support for ECMAScript 2015

We need to make a decision on what language this project will use, and whether we will transpile to other languages. If we want to use a transpiler, we need to support it both for Node.js and browser builds and tests.

Problem Description

There are four languages currently in active use in the JavaScript community. ECMAScript 2015, ECMAScript 5, CoffeeScript, and TypeScript. It also needs to support multiple runtimes: Browser and Node.js. We need to settle on which language to use, and how to support all of our targeted runtimes.

Proposed Change

This project will use ECMAScript 2015 as its primary language. Support for projects that do not support this language will be provided using Babel as a transpiler.

Setting up Babel

Babel should be configured using .babelrc file, so that configuration will be used for all the environments we're targeting.

{
  "presets": ["es2015"]
}

Node.js Build

We're targeting Node.js v4, which doesn't support all the ES2015 features, so usage of Babel is required. Babel can be integrated by specifying prepublish hook which runs Babel to transpile library's code and overriding main module in package.json.

{
  "main": "./dist/index.js",
  "scripts": {
    "build": "babel ./src --out-dir ./dist",
    "prepublish": "npm run build"
  }
}

Browser Build

Webpack will be used to create ES5 builds which are intended to run in browsers. babel-loader should be used to integrate Webpack and Babel.

Since node-fetch module which is used for sending HTTP requests isn't supposed to be run in browser environments, it should be substituted with whatwg-fetch polyfill using Webpack's node configuration option.

Here is an example of webpack.config.js file:

module.exports = {
  entry: [
    './src/index.js'
  ],
  output: {
    path: require('path').join(__dirname, '/dist/browser/'),
    chunkFilename: null,
    filename: 'openstack-lib-browser.js',
    sourceMapFilename: 'openstack-lib-browser.js.map'
  },
  module: {
    loaders: [
      {
        test: /\.js$/,
        loader: 'babel',
        exclude: [/node_modules\//],
        query: {cacheDirectory: true}
      }
    ]
  },
  node: {
    "node-fetch": "whatwg-fetch"
  }
};

Node.js Testing

It was agreed that we're using Jasmine for tests. Jasmine can be easily integrated with Babel by adding the following entry to `jasmine.json`:

{
  "helpers": [
    "../node_modules/babel-register/lib/node.js"
  ]
}

Browser Testing

One of the popular test runners Karma can be easily integrated with Babel and Webpack using karma-webpack plugin. There is also karma-babel-preprocessor module, but it's not needed since integration with Babel is described in webpack.config.js file.

Here is an example of karma.conf.js file:

module.exports = function(config) {

config.set({

browsers: ['Chrome', 'Firefox'], plugins: [ 'karma-webpack' ], preprocessors: { 'tests/*/.js': ['webpack'] }, webpack: require('./webpack.config')

});

};

Gulp Integration

The latest version of Gulp can be easily integrated with Babel just by renaming gulpfile.js to gulpfile.babel.js. Gulp will transpile the Gulpfile using Babel configuration from .babelrc file.

Implementation

Assignee(s)

Primary assignee:

vkramskikh

Gerrit Topic

Use Gerrit topic "jsdk_es2015" for all patches related to this spec.

git-review -t jsdk_es2015

Work Items

• Babel and related dependencies should be added.
• Babel configuration should be added.
• Jasmine and Karma configuration files should be updated to support Babel.
• Webpack should be added and configured to use Babel.
• NPM scripts to run node/browser builds/tests should be added to package.json.

Documentation

We will need project setup documentation for browsers and node applications. All documentation code samples should include examples using all available languages.

Testing

• All code samples should be tested.
• Our test suite should be run separately on each transpiled artifact.