PairDrop/docs/add-es2015-support-babel.md

Add ES2015 support through Babel

Although support for ES2015 (formerly ES6) is improving in modern browsers, the majority do not yet support the full set of features. To benefit from the awesomeness of the new ES2015 syntax while keeping backwards compatibility with Polymer's supported browsers, you'll need to transpile your JS code from ES2015 to ES5

This recipe focuses on adding an ES2015 to ES5 transpile step to Polymer Starter Kit's build pipeline using BabelJS.

Create a transpile gulp task

• Install the gulp Babel, Sourcemap, Crisper plugins and Babel ES2015 preset: npm install --save-dev gulp-babel gulp-sourcemaps gulp-crisper babel-preset-es2015
• Add the following gulp task in the gulpfile.js file:

+ // Transpile all JS to ES5.
+ gulp.task('js', function () {
+  return gulp.src(['app/**/*.{js,html}', '!app/bower_components/**/*'])
+    .pipe($.sourcemaps.init())
+    .pipe($.if('*.html', $.crisper({scriptInHead:false}))) // Extract JS from .html files
+    .pipe($.if('*.js', $.babel({
+      presets: ['es2015']
+    })))
+    .pipe($.sourcemaps.write('.'))
+    .pipe(gulp.dest('.tmp/'))
+    .pipe(gulp.dest(dist()));
+ });

This task will transpile all JS files and inline JS inside HTML files and also generate sourcemaps. The resulting files are generated in the .tmp and the dist folders

Crisper extracts JavaScript that's inline to HTML files (such as imports). We need this as Babel does not support transpiling HTML files such as <script> tags directly

Note: At the time of writing Crisper does not generate the sourcemaps. Your app will work but you won't get sourcemaps for files transformed by Crisper. Relevant issues:

• ragingwind/gulp-crisper#4
• PolymerLabs/crisper#14

Integrating the transpile task

Make sure the js gulp task is triggered by the common build tasks:

• In the gulp serve task, make sure js is triggered initially and on HTML and JS files changes:

-gulp.task('serve', ['lint', 'styles', 'elements', 'images'], function () {
+gulp.task('serve', ['lint', 'styles', 'elements', 'images', 'js'], function () {

  ...

- gulp.watch(['app/**/*.html'], reload);
+ gulp.watch(['app/**/*.html'], ['js', reload]);
  gulp.watch(['app/styles/**/*.css'], ['styles', reload]);
  gulp.watch(['app/elements/**/*.css'], ['elements', reload]);
- gulp.watch(['app/{scripts,elements}/**/{*.js,*.html}'], ['lint']);
+ gulp.watch(['app/{scripts,elements}/**/{*.js,*.html}'], ['lint', 'js']);
  gulp.watch(['app/images/**/*'], reload);
});

• In the default task make sure js is run in parallel to elements:

gulp.task('default', ['clean'], function (cb) {

  ...

  runSequence(
    ['copy', 'styles'],
-   'elements',
+   ['elements', 'js'],
    ['lint', 'images', 'fonts', 'html'],
    'vulcanize', // 'cache-config',
    cb);
});

• In the html task replace app in the paths by dist since dist should already contain all JS and HTML files now transpiled.

// Scan your HTML for assets & optimize them
gulp.task('html', function () {
  return optimizeHtmlTask(
-    ['app/**/*.html', '!app/{elements,test}/**/*.html'],
+    [dist('/**/*.html'), '!' + dist('/{elements,test}/**/*.html')],
    dist());
});

• In the optimizeHtmlTask function remove the searchPath attribute since all assets should be found under the dist folder and we want to make sure we are not picking up duplicates and un-transpiled JS files:

var optimizeHtmlTask = function (src, dest) {
- var assets = $.useref.assets({searchPath: ['.tmp', 'app', 'dist']});
+ var assets = $.useref.assets();

Configure linters for ES2015

• Enable ES2015 support in JSCS. Add "esnext": true to the .jscsrc file:

{
+ "esnext": true,
  "preset": "google",
  "disallowSpacesInAnonymousFunctionExpression": null,
  "excludeFiles": ["node_modules/**"]
}

• Enable ES2015 support in JSHint. Add "esnext": true to the .jshintrc file:

{
+ "esnext": true,
  "node": true,
  "browser": true,

Optional - When using shadow-dom instead shady-dom

Place this configuration (Read more) in a separate file like scripts/polymer-settings

<script>
    window.Polymer = window.Polymer || {};
    window.Polymer.dom = 'shadow';
</script>