Heroku Buildpack: WebAssets

This is a Heroku buildpack which compiles and minifies css, javascript & html assets.

Usage

Example usage:

$ ls -R *
_webassets.cfg              dynamicstyle.less           stylus.styl                 config.rb
sassystyle.scss             coffeescript.coffee         Cakefile                    main.js
html.jade                   package.json                Gruntfile.coffee

...

$ heroku create --stack cedar --buildpack https://github.com/abhishekmunie/heroku-buildpack-webassets.git
...

$ git push heroku master
...
-----> Heroku receiving push
-----> Fetching custom buildpack... cloning with git...done
-----> Web Assets app detected
...

The buildpack will detect your app as Web Assets if it has the file _webassets.cfg in the root.

This can be used in combination with ddollar/heroku-buildpack-multi in order to support more complex use-cases.

Features

• Supports Bower Package Manager
• Supports for custom plugins compile script
• Compiles LESS
• Compiles Stylus
• Compiles SASS & SCSS with support for Compass
• Supports Recess Lint and Compile
• Compress css using YUI Compressor - 2.4.7
• Creates hash name copy of css files using first 8 characters of its sha1
• Compiles CoffeeScripts with support for Cake
• Supports importer
• Supports Require.js
• Compiles JavaScripts using Google Closure Compiler
• Creates hash name copy of js files using first 8 characters of its sha1
• Compiles Jade
• Minifies HTML using html-minfier
• Removes LESS, Stylus, SASS, SCSS, CoffeeScript & Jade files once compilation is done for each type.
• Supports Source Maps for CoffeeScript, Importer & Closure Compiler
• Supports Grunt for a custom build

Configuration

The buildpack reads its configuration from _webassets.cfg using $ source _webassets.cfg. The options marked with *** if set will disable all operations under it. By default none of these options are set, except if explicitly specified.

EXCLUDE_DIRS                  : List of directories to be excluded, seperated by '|'.
                                (Default: '\..*|_.*|bak|config|sql|fla|psd|ini|log|sh|inc|swp|dist|tmp|node_modules|bin|plugins|libs|components)'

GRUNT_ONLY                    : Only uses Grunt to process assets *

  NO_SOURCE_MAP               : Doesn't generates source map

  NO_BOWER                    : Disables Bower *
    BOWER_OPTIONS             : Options that would be passed to `$ bower install `

  NO_CSS                      : Disables CSS related processings *

    NO_LESS                   : Disables LESS *
      LESS_OPTIONS            : Options that would be passed to `$ lessc `

    NO_STYLUS                 : Disables Stylus *
      STYLUS_OPTIONS          : Options that would be passed to `$ stylus `

    NO_SASS                   : Disables SASS *
      SASS_OPTIONS            : Options that would be passed to `$ sass - --update `
      COMPASS_OPTIONS         : Options that would be passed to `$ compass compile `

    NO_RECESS                 : Disable Recess *
      RECESS_LINT_OPTIONS     : Options that would be passed to `$ recess `
      RECESS_COMPILE_OPTIONS  : Options that would be passed to `$ recess --compile `
    NO_CSS_MIN                : Disables CSS Minifier *
      YUICOMPRESSOR_OPTIONS   : Options that would be passed to `$ java -jar yuicompressor-2.4.7.jar --type css `

  NO_JS                       : Disables JS related processings *

    NO_COFFEE_SCRIPT          : Disables CoffeeScript *
      CAKE_OPTIONS            : Options that would be passed to `$ cake build `
      NO_CS_IMPORTER          : Disables Importer for CoffeeScripts *
        IMPORTER_CS_OPTIONS   : Options that would be passed to `$ importer ` when used on .coffee
      CS_OPTIONS              : Options that would be passed to `$ coffee - --compile --output `

    NO_JS_IMPORTER            : Disables Importer for JavaScripts *
      IMPORTER_JS_OPTIONS     : Options that would be passed to `$ importer ` when used on .js

    USE_REQUIREJS             : Enables Require.js
      REQUIREJS_OPTIONS       : Options that would be passed to `$ r.js -o baseUrl=$BUILD_DIR `

    NO_CLOSURE_COMPILE        : Disables Google Closure Compiler*
      CLOSURE_COMPILE_OPTIONS : Options that would be passed to `$ java -jar compiler.jar `

  NO_HTML                     : Disables HTML related processings *
    NO_JADE                   : Disable Jade *
      JADE_OPTIONS            : Options that would be passed to `$ jade `
    NO_HTML_COMPRESSION       : Disables HTML Minifier *
      HTML_COMPRESSOR_OPTIONS : Options that would be passed to `$ java -jar htmlcompressor-1.5.3.jar  `
                                (Default: --recursive --simple-bool-attr --preserve-server-script --compress-css --compress-js --js-compressor closure -o)


USE_GRUNT                     : Uses grunt
  GRUNT_OPTIONS               : Options that would be passed to `$ grunt `

Hacking

To modify this buildpack, fork it on Github. Push up changes to your fork, then create a test app with --buildpack <your-github-url> and push to it.

It starts with installing node, node modules and other dependencies. Then the following are processed:

Bower

Runs $ bower install to install Bower components.

CSS

• Runs $ ./plugins/compile if exists to compile plugins.
• Uses LESS node.js command-line binary to compile filename.less to filename.scss, excluding files in */plugins/* It simply runs $ lessc "$filename.less" > "$filename.scss" on all .less files. If SCSS is disabled it compiles to filename.css
• Removes .less files
• compiles stylus using stylus node module $ stylus
• Removes .styl files
• Followed by SASS Ruby gem to compile .scss & .sass files, excluding files in */plugins/* usng $ sass --update $BUILD_DIR:$BUILD_DIR
• If the app has config.rb in root, Compass will be used inplace of standard scss compilation.
• Removes .sass and .scss files
• Runs recess lint and compile.
• Uses YUI Compressor to minify filename.css and create filename.min.css. It simply runs $ java -jar yuicompressor-2.4.7.jar --type css on all .css files except those ending in .min.css.
• It also creates a copy of filename.min.css file with first 8 characters of its sha1 (filename.<sha1:0:8>.css).

JS

• If repo has Cakefile in root it will be used instead to compile CoffeeScripts.
• if no Cakefile, imports coffee-scripts using importer
• If NO_CS_IMPORTER is set, uses coffee-script Node.js utility to compile all filename.coffee to filename.js by running $ coffee --compile --output ${BUILD_DIR} ${BUILD_DIR}.
• Removes .coffee files
• Unless NO_JS_IMPORTER is set, imports javascripts using importer
• Runs requirejs $ r.js -o baseUrl=$BUILD_DIR
• Uses Google Closure Compiler to minify filename.js and create filename.min.js. Simply runs $ java -jar compiler.jar on all .js files except those ending in .min.js. To customize compilation see Annotating JavaScript for the Closure Compiler and Advanced Compilation and Externs.
• It also creates a copy of filename.min.js file with first 8 characters of its sha1 (filename.<sha1:0:8>.js). Files in 'libs' directories will be ignored.

HTML

• Compiles Jade using $ jade $BUILD_DIR
• Removes .jade files
• Minfies all HTML using htmlcompressor

Grunt

Just $ cd $BUILD_DIR and runs $ grunt .