Precompilation and Tooling (Bundling, CSS, ES6)

[pheara]

Motivation

We could use a bundling-tool, to improve page-load-times (and mitigate the need to add every js-file to index.jsp) and allow us to use dependency managment / requires also on non-angular scripts. Angular 1.4 offers CommonJS exports - any system that can work with this format should be easy to use with Angular. As a side-effect, having a compilation-step/pipeline also frees us to use a more powerful styling-language (e.g. scss, less, myth, jss).

Angular 1.4's CommonJS support

Candidates

Options for this are:

• webpack
• requirejs
• node-browserify
• jspm-cli

[pheara]

Tutorials and Boilerplates

The following repo contains boilerplate for building angular, sass and ES6 via gulp, browserify, babel and uglify. Thus it's a full stack and relatively well documented and organized: https://github.com/jakemmarsh/angularjs-gulp-browserify-boilerplate

A slightly smaller/simpler tooling/boilerplate: https://github.com/mrkrstphr/angular-js-boilerplate/

And another, even smaller: https://github.com/grudelsud/angularjs-gulp-browserify-boilerplate

No Angular here, but apparently good gulp best-practices: https://github.com/greypants/gulp-starter

angular1.4-ES6-material-webpack-boilerplate

Webpack & Angular: Part 1 by Shawn McKay

A tutorial for angular + gulp + browserify: http://mindthecode.com/lets-build-an-angularjs-app-with-browserify-and-gulp

...with AngularJS 1.4, ECMAScript 6, Material Design and Webpack

AngularJS And Browserify — The Dream Team For Single Page Applications by Bastian Krol (2014/08) compared different project setups for developing angular projects or rather stages of code-organisation, showcasing his points with code snippets.

[pheara]

In case we need to use libs that don't offer commonjs exports by themselves, we can use browserify-shim for that.

[pheara]

Distinct Approaches

Bundling

• webpack
• browserify (used with gulp and uglify)
• jspm

Webpack and Browserify seem to be relatively interchangeable. Switching requires to rewrite the build-configuration though. Jspm on the other hand uses ES6-style imports (but backwards-compatible to the RequireJS style)

Styling

• scss (used with gulp)
• myth
• jss

No matter which of the above we use, gulp-autoprefixer should solve the hassle with vendor-prefixes. This handy page lists examples for specifying which browsers should be supported.

ES6

• babel
• traceur

Using ES6 gives us a bunch of syntactical sugar that eases development and improves code readability.

[pheara]

ES6

Practical Workflows for ES6 Modules

ES6 Module Transpiler

Dr Axex Rauschmayer on ES6-module-syntax (2014/09) and Using ES6 Today (2014/08)

A good set of examples of ES6's capabilities can be found on the babel-homepage. They also have a sandbox/playground where you can try these out (the right column is the generated ES5 code and below it any console output. You can also find the output in your browser's console.)

A good "Angular 1.X + ES6"-styleguide.

Writing AngularJS Apps Using ES6 by Ravi (2015/01) contains code-snippets for all major angular-building-blocks.

Traceur vs Babel

Both are ES6 to ES5 transpilers. Traceur requires a small runtime, babel only shows up as dependency for transpiling and seems to produce better readable code that's closer to the original. On the other hand, the latter doesn't matter much, as we'll have source-maps to minified code.

Transpiling EcmaScript6 code to ES5 using Babel by Jonathan Petitcolas (2015/03) have decided for Babel for their Angular and React App due to it not needing a runtime and having a REPL on their homepage. Although, they're using it along-side the polyfill Core.js

Transpiling Wars: BabelJS vs Traceur by Dwayne Charrington (2015/01) points slightly towards Babel for producing better readable code and having support for jsx (which doesn't matter for us)

http://stackoverflow.com/questions/28447132/should-i-use-babel-or-google-traceur-to-compile-my-es6-code

Summary: The difference isn't big, but Babel has a few advantages.

[pheara]

Bundling

I've started to just test out the alternatives in a clean repo:

-----> https://github.com/m0ru/tooling-for-angular-1.4 <-----

A (probably biased) comparison on the webpack-homepage: http://webpack.github.io/docs/comparison.html

Browserify vs Webpack

browserify for webpack users by Substack points out that Browserify adheres more the Unix-philosophy of single-purpose tools. It has to be noted, that Substack is a developer on the browserify-team.

Browserify vs Webpack by Naman Goel (2015/01) addresses Substack's post and gives an apparently relative neutral comparison between the two tools' approaches. My attempt of summarizing the summary:

• Webpack always requires a medium sized configuration, browserify makes a few assumptions that require small changes in the project structure but reduce the configuration effort. It also nudges one to (npm-)modularize the project more strongly.
• Browserify is part of a ecosystem of independent tools whereas webpack is a single tool (with plugins)
• browserify is node-conform and enables easier interaction with the node-ecosystem (e.g. file-reading)
• webpack has hotloading if configured
• webpack comes with a longer list of features whereas browserify has a smaller, 'well-designed' API (compared to browserify)

From the summary of Browserify vs Webpack by Naman Goel (2015/01) :

...

So, if you make your decisions only based on checklists of features, or if one of the features that are unique to Webpack are extremely important to you, like Hot-Loading, then Webpack is right choice for you.

If however, you’re predominantly dependent on the NPM ecosystem and you want a tool with a small and very well designed API and takes minimal configuration, you should go for Browserify.

...

In general, I prefer Browserify as it amazingly easy to get started with and plays very well with the node and npm ecosystem. I don’t see the value of requiring CSS files in my javascript usually, and images ever. That said, if a project grows very large, and I need complicated solutions that are easier with webpack, I will just transition from browserify to webpack just for that project.

...

Browserify

Getting ES6 modules working thanks to Browserify, Babel, and Gulp

Webpack

Using ES6-modules with webpack

JSPM

http://jspm.io

How to start writing apps with ES6, Angular 1.x and JSPM by Martin Micunda (2015/02)

In contrast to the other two, JSPM hasn't been added to the Frontend-Maven-Plugin we're using yet. UPDATE: Support for it has just been merged.

As a package-manager jspm can pull from the bower-registry, npm-registry, it's own registry, github and more.

Systemjs can import ES6-, RequireJS- and AMD-style as well as other file-types like CSS and HTML-templates (by virtue of being ES6, see here).

[pheara]

CSS Pipeline

Style Guides

This section contains good-to-know best-practices for everyday styling. Making these best-practices easier to use/implement factors into the decision which language to use for styling.

Some bad practies in writing CSS and how to avoid them: Used and Abused – CSS Inheritance and Our Misuse of the Cascade by Micah Godbolt (2014/08) suggests an alternative style to BEM and OOCSS

Extending silent classes in Sass on CSS-Wizardry (2014/01) in context with Extending Placeholder Selectors with Sass by Guil Hernandez (2013/04) who describes the motivations of silent classes and how to use them in SASS. Most of all others they allow to reduce the size of the exported code.

JSS

As it's js-based (and compiles to css), it allows using dependency-managment (and everything else js has to offer) and should help with bundling component-specific with these while still maintaining an general app/core-style and even with including util-classes as required. Of course, it should be mentioned here, that SCSS has it's own mechanism for includes.

A syntax-overview and some good references can be found on the jss github-page. The most important reference woulde be JSS - The important parts. by Oleg Slobodskoi (2015/01). The following quotes are taken from the latter article:

CSS hasn’t been designed to fit into components based architecture. Every selector you write is global. There is no good way to avoid conflicts when integrating third party components or even written by someone from the team.

JSS has facilities to solve this via generated class names at compile time.

Running JSS purely introduces a runtime overhead as the css-rules are generated on the client. There's a prepackaged gulp-stream-transformer gulp-jss that would do this server-side and export a single css. However I couldn't get the transformer to work for me in a sensible amount of time.

SCSS

SCSS is one of the best known CSS-preprocessor-languages. Tool-support for is good, there are many (bootstrap-)themes written in it, it's backward compatible to pure CSS and we've used it for the Meinkauf-Shoppinglist-App. All-in-all it'd be a solid choice.

Myth

Myth is a polyfill for CSS4. However it doesn't offer nesting, extends and includes. Next to variables, in my eyes these are the main points for using a css-precompiler.

Summary

SCSS works without runtime-overhead, has the most useful feature-set and the best tool-support.

[pheara]

Summary

The stack best suited to our setup and situation seems to consist out of:

• Angular 1.X (see #300)
• JSPM for bundling
• Babel as ES6 transpiler
• SCSS as CSS-precompiler
• Autoprefixer for CSS-vendor-prefixing.

EDIT: I just found another useful utility in our MeinkaufShoppinglist-setup: clean-css for minifying our css.

[pheara]

This stuff has been implemented for a while now ^^"