Skip to content

Latest commit

 

History

History
288 lines (189 loc) · 7.04 KB

README.md

File metadata and controls

288 lines (189 loc) · 7.04 KB
Raw

Flour

NPM version

Flour is a set of simple build tools for your Cakefiles.

Changelog

image

Usage

Add flour and your required pre-processors/compilers to your package.json:

{
  "name": "dancingrobot",
  ...
  "dependencies": {
    "flour": "",
    "uglify-js": "",
    "coffee-script": ""
  },
  ...
}

Then run npm install, and require 'flour' at the top of your Cakefile. A few methods are available in the global scope.

This is what a typical Cakefile could look like:

require 'flour'

task 'build:coffee', ->
    compile 'coffee/app.coffee', 'js/app.js'

task 'build:less', ->
    compile 'less/main.less', 'css/main.css'

task 'build:plugins', ->
    bundle [
        'vendor/underscore.js'
        'vendor/hogan.js'
        'vendor/backbone.js'
    ], 'js/plugins.js'

task 'build', ->
    invoke 'build:plugins'
    invoke 'build:coffee'
    invoke 'build:less

task 'watch', ->
    invoke 'build:less'
    invoke 'build:coffee'

    watch 'less/*.less', -> invoke 'build:less'
    watch 'coffee/app.coffee', -> invoke 'build:coffee'

task 'lint', 'Check javascript syntax', ->
    lint 'js/feature.js'

(if the global pollution hurts your feelings you can remove them with flour.noConflict(). That will bring the global object back to it's previous state)

Each of these functions accepts either a file path or a list of files. Simple wildcard paths (*.xxx) are allowed. For example:

watch [
    'less/main.less'
    'less/reset.less'
    'less/print.less'
], -> invoke 'build:less'

You can also access the resulting output by passing a callback:

compile 'coffee/app.coffee', (output) ->
    # do something with the compiled output
    mail.send subject: 'Project file', to: '[email protected]', body: output

# verify the CoffeeScript compiler output
compile 'coffee/app.coffee', 'js/app.js', -> lint 'js/app.js'

Adapters

These are the current adapters and the required modules:

Compilers

  • CoffeeScript: coffee-script
  • LESS: less
  • Stylus: stylus

Minifiers

  • Javascript: uglify-js

Linters

  • Javascript: 'jshint'

Creating new adapters is very easy, take a look at the adapters/ folder for guidance.

Reference

Compile

Compile CoffeeScript, LESS, Stylus, Handlebars templates:

compile(file, [destination], [callback])
Usage
compile 'app.coffee', 'app.js'

compile 'cold.coffee', 'app.js', (output) ->
    console.log 'Done!'

compile 'cold.coffee', (output) ->
    console.log output.transform()

Some compilers may accept options that will get proxied to their respective libraries. For example, you can disable compression for LESS or Stylus with

flour.compilers.less.compress = false
flour.compilers.styl.compress = false

Or customize the LESS include path with

flour.compilers.less.paths = ['/path/to/my/less/libs/']

Bundle

Compile, minify and join a set of files:

bundle(files, destination)
Usage
// preservers the list order
bundle [
    'lib/jquery.js'
    'lib/underscore.js'
    'lib/backbone.js'
], 'js/bundle.js'

// system-dependent order
bundle 'js/*.js', 'js/all.js'

Watch

Watch files for changes:

watch(files, action)
Usage
watch 'src/app.coffee', ->
    compile 'lib/app.js'

# best used with predefined tasks:

task 'build', ->
    bundle '*.coffee', 'app.js'

task 'watch', ->
    watch [
        'modules.coffee'
        'user.coffee'
        'main.coffee'
    ], ->
        invoke 'build'

# or simply
task 'watch', ->
    watch '*.coffee', -> invoke 'build'

Lint

Check file syntax (uses JSHint):

lint(file, [options], [globals]) # see http://www.jshint.com/options/

Usage

task 'lint', ->

    lint 'scripts/*.js'

Minify

Minify files (currently only Javascript using UglifyJS):

minify(file, [destination], [callback])

Extensibility

You can add new minifiers and compilers to flour:

flour.minifiers['dumb'] = (file, cb) ->
    file.read (code) ->
        cb code.replace(/\s*/, '')

flour.compilers['odd'] = (file, cb) ->
    odd = require 'odd-lib'
    file.read (code) ->
        cb odd.compile code

Tips

Disable the JS minifier during development

task 'watch', ->
    flour.minifiers.disable 'js'

    watch 'scripts/*.coffee', -> invoke 'build'

Pre-compile Hogan templates

flour.compilers['mustache'] = (file, cb) ->
    hogan = require 'hogan.js'
    file.read (code) ->
        cb "App.templates['#{file.base}']=${hogan.compile code, asString: true};"

task 'build:templates', ->
    bundle 'views/*.mustache', 'resources/views.js'

Why use flour?

While Grunt, brewerjs, H5BP-build-script, Yeoman and other similar projects have the same (and some more advanced) capabilities, they are increasingly complex to setup.

The goal of Flour is to provide a small and simple API that caters for the most common build tasks, without requiring you to adjust your project structure, install command-line tools or create long configuration files.

Changelog

v0.5.4
  • enable options forwarding for minifiers
  • fix bundle behaviour when no output path given
v0.5.2
  • coffeescript sourcemap support
v0.5.1
  • pass through all options to adapters. white-listing is not mantainable.
  • add markdown compiler
v0.5
  • flour.minifiers.disable('js'), enables/disables all if no argument given
  • compile handlebars *.hbs templates
v0.4.12
  • expand paths containing patterns inside bundle() array argument (#22)
v0.4.11
  • mkdir_p on compile (#20)
v0.4.10
  • compatibility fix for CoffeeScript 1.5.0
v0.4.9
  • fix lint callback arguments
  • breaking change: call callback only once when watching multiple files. each file is a key in the results object
  • add yuicompress option for LESS compiler
v0.4.8
  • output to multiple files with flour.compile 'src/*.coffee', '*' and variations
v0.4.5 / v0.4.6
  • handle single file path as input for bundle()
  • better handling of wildcard paths using minimatch
v0.4.4
  • add back support for uglify-js < 2.0
v0.4.0
  • tests!
  • fix file buffer bug
  • accept options for adapters, enables disabling compression for LESS and Stylus
v0.3.3
  • bugfixes
v0.3.2
  • add node-hound as a dependency for file watching
  • watch whole directory trees: watch src/`, -> invoke 'build' (listens for new files and deletes too)
  • fix error handlers leak
v0.3.1
  • fix extension handling bug
v0.3.0
  • flour doesn't install it's adapter dependencies anymore, it's up to you to add them to your project's package.json