Spec for ECMAScript 2015 and Transpiler support
This spec describes how we're going to handle delivering artifacts to more than one platform. Change-Id: I42fa0754c08ecd05891f31f87d7c046b5fc8bc07
This commit is contained in:
parent
81f50b8b99
commit
c7286cc7d3
|
@ -34,6 +34,7 @@ permits.
|
|||
:maxdepth: 1
|
||||
|
||||
specs/devstack
|
||||
specs/es2015.rst
|
||||
|
||||
|
||||
Implemented Specifications
|
||||
|
|
|
@ -0,0 +1,187 @@
|
|||
::
|
||||
|
||||
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.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"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`.
|
||||
|
||||
.. code-block:: 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:
|
||||
|
||||
.. code-block:: javascript
|
||||
|
||||
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`:
|
||||
|
||||
.. code-block:: 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:
|
||||
|
||||
.. code-block:: javascript
|
||||
|
||||
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.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
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.
|
Loading…
Reference in New Issue