Brunch DocumentationRelease 1.3.4

Brunch team

July 07, 2012

CONTENTS

i

ii

Brunch Documentation, Release 1.3.4

Brunch is an assembler for HTML5 applications. It’s agnostic to frameworks, libraries, programming, stylesheet &templating languages and backend technology.

To simplify app development, brunch watches your files for changes and automatically wraps your scripts and tem-plates in common.js modules. All build errors are printed to console. If you have growl / libnotify, brunch will usethem too.

See official site for more information about the tool http://brunch.io.

Contents:

CONTENTS 1

Brunch Documentation, Release 1.3.4

2 CONTENTS

CHAPTER

ONE

FAQ

1.1 I want to start new project with Brunch. What’s the workflow?

• Create new project (preferably from brunch-with-chaplin skeleton if you’re building big app) brunch newproject --skeleton git://github.com/paulmillr/brunch-with-chaplin.git &&cd project.

• Create HTML mockups in app/assets directory (login.html, user.html etc.) & corresponding styles.

• Watch application files with brunch watch --server and see the results in browser onlocalhost:3000. Auto-debug styles in browser with auto-reload-brunch which will automat-ically reload browser page on every page.

• When all mockups are done, create app classes for them with brunch generate. E.g. brunchgenerate scaffold user.

• Debug your code in browser via console.log or debugger statements.

1.2 I don’t like CoffeeScript. Does brunch work for pure js projects?

Yep! Execute brunch new project_name --skeleton git://github.com/brunch/simple-js-skeleton.gitand you’ll create a javascript project. Customize it to your needs.

1.3 How do I change app language?

For example, you want to change default Handlebars templates to eco.

• Remove "handlebars-brunch": "version" line from package.json.

• Add "eco-brunch": "version" there

• Change config.files.templates.defaultExtension to eco in config.coffee.

1.4 What version of plugin do I need to use? There are eco-brunch1.0.1, 1.1.0 etc.

Brunch x.y.z releases are compatible with plugins (in this case eco-brunch) x.(<= y).*. It means that:

You can use:

3

Brunch Documentation, Release 1.3.4

• brunch 1.1.0 with plugin 1.0.0.

• brunch 1.1.0 with plugin 1.1.9.

• brunch 1.9.14 with plugin 1.5.6.

You can’t use:

• brunch 1.1.0 with plugin 1.2.0.

• brunch 1.1.0 with plugin 2.0.0.

• brunch 2.0.0 with plugin 1.2.0.

1.5 Why do you use these languages in default skeletons?

• CoffeeScript is used because it plays nice with object-oriented Backbone.js nature.

• Stylus is used because a) it has customizable syntax (you can use or drop braces / semicolons / :‘s), unlike less/ sass; b) its mixins are transparent. If you’re writing ‘‘border-radius‘ in stylus with nib, it’s automaticallyexpanded to all vendor prefixes. No need to use LESS / SCSS syntax. Example: https://gist.github.com/2005644.

• Handlebars templates are used because they are logic-less / compatible with Mustache (that has implementationsin many languages) and have nice helpers system. If you’re a fan of clear syntax, you might like Jade instead,which is much clearer than HAML.

4 Chapter 1. FAQ

CHAPTER

TWO

COMMAND LINE API

2.1 brunch new <rootPath>

Create new brunch project. Options:

• rootPath: (required) name of project directory that would be created

• -s PATH_TO_SKELETON, --skeleton PATH_TO_SKELETON: path or

git repo address of project, contents of which will be copied to new dir.

.git directory is automatically removed when copying.

Short-cut: brunch n.

Examples:

• brunch n twitter -s ~/brunch-templates/simple

• brunch n twitter -s git://github.com/paulmillr/brunch-with-chaplin.git

2.2 brunch build

Build a brunch project. Options:

• -m, --minify: minify the result js & css files? Analog of minify option in config file.

• -c CONFIG_PATH, --config CONFIG_PATH: path to config (default: config)

• -o PUBLIC_DIR, --public PUBLIC_DIR: path to public directory (a place to which brunch wouldcompile files)

Short-cut: brunch b.

Examples:

• brunch b -c ios_config -m: would load ios_config.(js,coffee), build application and minify the out-put.

• brunch b -m -o /home/www/site: build application to /home/www/site and minify output.

2.3 brunch watch

Watch brunch directory and rebuild if something changed. Options:

5

Brunch Documentation, Release 1.3.4

• -s, --server: run a simple http server that would server output dir in / and test dir in /test/

• -p PORT, --port PORT: if a server option was specified, define on which port the server would run

• -c CONFIG_PATH, --config CONFIG_PATH: path to config (default: config)

• -m, --minify: minify the result js & css files? Analog of minify option in config file.

• -o PUBLIC_DIR, --public PUBLIC_DIR: path to public directory (a place to which brunch wouldcompile files)

Short-cut: brunch w.

Examples:

• brunch w: simply watch current directory &amp; compile the output to build directory.

• brunch w -s: watch current project and run a webserver that would work on public directory (by default).

• brunch w -s -p 8841 -m -o /home/www/site: watch current project, compile files in/home/www/site and run a webserver that would work on /home/www/site directory. Also,auto-minify files.

2.4 brunch generate <type> <name>

Generate file for current project. Options:

• type: (required) generator type.

• name: (required) generator class name / filename.

• -p PATH_TO_DIRECTORY --path PATH_TO_DIRECTORY: path to directory in which file will be cre-ated. Useful if you prefer non-standard directory structure.

• --plural FORM: plural form of <name>.

Content of generated file depends on plugins and config.generators setting in config.

Generator types for config.framework = ’backbone’:

• model

• collection (uses plural version)

• template

• style

• view (also generates template & style)

• scaffold (generates model & view)

Generator types for config.framework = ’chaplin’:

• controller (uses plural version)

• model

• collection (uses plural version)

• template

• style

• view (also generates template & style)

• collectionView (uses plural version, also generates style)

6 Chapter 2. Command line API

Brunch Documentation, Release 1.3.4

• scaffold (generates controller, model & view)

Short-cut: brunch g.

Examples:

• brunch generate model user: would generate file app/models/user.coffee with class Userand a unit-test test/models/user.coffee.

• brunch generate collection user: would generate file app/models/users.coffee withclass Users and a unit-test test/models/users.coffee.

• brunch generate scaffold news --plural feed: would generate fileapp/models/feed.coffee with class Feed and a unit-test test/models/feed.coffee.

2.5 brunch destroy <type> <name>

Destroy model, view or route for current project, created by brunch generate. Options:

• type: (required) generator type. One of: collection, model, router, style, template, view.

• name: (required) generator class name / filename.

• -p PATH_TO_DIRECTORY --path PATH_TO_DIRECTORY: path to directory in which file will bedeleted. Useful if you prefer non-standard directory structure.

Short-cut: brunch d.

Examples:

• brunch destroy collection user_list: would remove file app/collections/user_list.coffeewith class UserList and a unit-test test/unit/collections/user_list.coffee.

• brunch d model post -p app/twitter/models: would remove fileapp/twitter/models/post.coffee with class Post and a unit-testtest/unit/twitter/models/post.coffee.

2.6 brunch test

Run tests on the current project. Options:

• -c CONFIG_PATH, --config CONFIG_PATH: path to config (default: config)

Short-cut: brunch t.

2.5. brunch destroy <type> <name> 7

Brunch Documentation, Release 1.3.4

8 Chapter 2. Command line API

CHAPTER

THREE

CONFIGURATION FILE

Brunch uses configuration file (config.coffee or config.js) located in the root directory to control variousaspects of your application.

3.1 paths

Optional, object: paths contains application paths to key directories. Paths are simple strings.

• public key: path to build directory that would contain output.

• ignored key: string, regExp, function or array of them. Will check against files that would be ignored bybrunch compilator.

• assets key: path OR array of paths to asset files.

• Other valid keys, but not recommended to use: test, app, vendor, root.

Example:

paths:public: ’../deploy’ignored: ’vendor/styles/bootstrap’test: ’spec’

3.2 files

Required, object: files configures handling of application files: which compiler would be used on which file, whatname should output file have etc.

• <type>: javascripts, stylesheets or templates

– defaultExtension: (optional). Defines what file will be generated with brunch generate.

– joinTo: (required) describes how files will be compiled & joined together. Available formats:

* ‘outputFilePath’

* map of (‘outputFilePath’: /regExp that matches input path/)

* map of (‘outputFilePath’: function that takes input path)

– order: (optional) defines compilation order. vendor files will be compiled before other ones even if they are not present here.

* before: list of files that will be loaded before other files

9

Brunch Documentation, Release 1.3.4

* after: list of files that will be loaded after other files

Note: all files from vendor directory are automatically (by-default) loaded before all files from app directory. So,vendor/scripts/jquery.js would be loaded before app/script.js even if order config is empty.

Example:

files:javascripts:defaultExtension: ’coffee’joinTo:

’javascripts/app.js’: /^app/’javascripts/vendor.js’: /^vendor/

order:before: [

’vendor/scripts/console-helper.js’,’vendor/scripts/jquery-1.7.js’,’vendor/scripts/underscore-1.3.1.js’,’vendor/scripts/backbone-0.9.0.js’

]

stylesheets:defaultExtension: ’styl’joinTo: ’stylesheets/app.css’order:

before: [’vendor/styles/normalize.css’]after: [’vendor/styles/helpers.css’]

templates:defaultExtension: ’eco’joinTo: ’javascripts/app.js’

3.3 generators

Optional, object: contains templates that would be used with brunch generate command. For example, if thereis generators.model and you execute brunch generate model twitter_user, brunch will call / loadgenerators.model. This param is optional and by default it uses some predefined templates. Template could be:

1. A string.

2. A function, that will take name, entered in brunch generate.

Example:

generators:# formatClassName is a custom function that converts# aaa_bbb_ccc to AaaBbbCccmodel: (name) -> ’class #{formatClassName name} extends Backbone.Model’view: fs.readFileSync sysPath.join __dirname, ’generators’, ’view’

3.4 framework

Optional, string: framework you’ll be using as skeleton of your app.

Default value is ’backbone’.

10 Chapter 3. Configuration file

Brunch Documentation, Release 1.3.4

Examples: ’backbone’, ’chaplin’, ’ember’, ’batman’.

3.5 minify

Optional, boolean: determines if minifiers should be enabled or not.

Default value is false.

Examples: true, false.

3.6 server

Optional, object: contains params of webserver that runs on brunch watch --server.

• path: (optional) path to nodejs file that will be loaded. The file must contain exports.startServerfunction.

• port: (optional) port on which server will run

• base: (optional) base URL from which to serve the app

• run: should the server be launched with brunch watch?

Example:

server:path: ’server.coffee’port: 6832base: ’/myapp’run: yes

3.5. minify 11

Brunch Documentation, Release 1.3.4

12 Chapter 3. Configuration file

CHAPTER

FOUR

PLUGINS

Brunch uses asynchronous node.js plugins to provide compilation / minification functional.

4.1 Usage

Add “<plugin-npm-name>”: “<plugin-version>” to package.json of your brunch app.

Pick a plugin version that corresponds to your minor (y) brunch version.

If you want to use git version of plugin, add “<plugin-npm-name>”: “<git-repo>”.

Examples:

"javascript-brunch": "1.3.5""sass-brunch": "git+ssh://git@github.com:brunch/sass-brunch.git"

4.2 API

Brunch language is a CoffeeScript class that has brunchPlugin property. It would be initialized with applicationconfig (you can access it by using @config instance variable).

• brunchPlugin: (required, boolean) it’s always truthy for brunch plugins. By this field, brunch determines ifcurrent package is a real plugin or just random server-side thing.

• type: (required in compilers & minifiers, string)

• extension: (required in compilers, string)

• compile(data, path, callback): (required in compilers, function) would be called every timebrunch sees change in application source code. Data is contents of source file which will be compiled, pathis path to the file and callback is a function that will be executed on compilation with arguments error andresult.

• getDependencies(data, path, callback): (required in compilers, function) would be called everytime brunch sees change in application source code. Used as chain compilation rule. For example, if _user.stylchanges

and main.styl depends on it, main.styl will be recompiled too. To know this, brunch needs to receive an array ofdependent files from the function. * minify(data, path, callback): (required in minifiers, function) wouldbe called every time brunch sees change in application source code. Data is contents of destination file which will beminified, path is path to the file and callback is a function that will be executed on compilation with arguments error

13

Brunch Documentation, Release 1.3.4

and result. * onCompile: (optional, function) would be called every time after brunch walks through the wholecompilation circle. Could be useful if you make browser autoreload plugin etc.

Example:

CSSCompiler would simply read the file and return its contents.

module.exports = class CSSCompilerbrunchPlugin: yestype: ’stylesheet’extension: ’css’

constructor: (@config) ->null

compile: (data, path, callback) ->callback null, data

See wiki page for a list of plugins. Feel free to add new plugins there.

wiki page: https://github.com/brunch/brunch/wiki/Plugins

14 Chapter 4. Plugins

CHAPTER

FIVE

SKELETONS

Brunch uses skeletons to provide pre-defined application structure.

Main parts of every skeleton:

• App path (usually app/ ): place for user’s code should be.

• Vendor path (usually vendor/ ): place for 3rd party libs should be.

• Config (usually config.coffee): defines application configuration

• Test path (usually test/ ): place for tests.

15

Brunch Documentation, Release 1.3.4

16 Chapter 5. Skeletons

CHAPTER

SIX

UPGRADING BRUNCH

6.1 Upgrading to 1.3

• Add test files joinTo configuration to your config file. You can look at https://github.com/paulmillr/brunch-with-chaplin/blob/master/config.coffee as an example.

• Add test files as in example https://github.com/paulmillr/brunch-with-chaplin/tree/master/test

• Update package.json brunch plugins versions to >= 1.0 < 1.4

• Run npm install

6.2 Upgrading to 1.2

• Update package.json brunch plugins versions to >= 1.0 < 1.3

• Run npm install

6.3 Upgrading to 1.1

• Change buildPath: ... in config.coffee to paths: public: ...

• Update package.json brunch plugins versions to >= 1.0 < 1.2

• Run npm install

6.4 Upgrading to 1.0

• Edit config:

– Remove plugins section, as it has been moved to package.json.

– Remove defaultExtensions section.

– Edit files section to conform to new config API.

• Remove node_modules/ directory. Install plugins you need by editing package.json and executing npminstall after it.

• Upgrade backbone & jquery to latest versions (optional).

17

Brunch Documentation, Release 1.3.4

6.5 Upgrading to 0.9

• Move src/app to app and src/vendor to vendor/scripts

• Move all files that you were putting to build directory out of there, to app/assets. build is now generatedautomatically. Create app/assets if it doesn’t exist.

• Upgrade vendor/scripts/backbone-0.5.2.js to vendor/scripts/backbone-0.5.3.jsand vendor/scripts/jquery-1.6.2.js to vendor/scripts/jquery-1.7.js.

• Rename vendor/scripts/ConsoleDummy.js to vendor/scripts/console-helper.js.

• Create package.json and config.coffee. You can copy them from new brunch applica-tion (brunch new app && cp app/package.json app/config.coffee && rm -rf app).Though, config.coffee would require some editing if you’ve edited config.yaml previously.

• Execute npm install.

6.6 Upgrading to 0.8

• Update Vendor. First of all you need upgrade files from brunch/src/vendor:

– backbone-master.js -> backbone-0.5.2.js

– ConsoleDummy.js

– jquery-1.5.2.js -> jquery-1.6.2.js

– underscore-1.1.5.js -> underscore-1.1.7.js

• Upgrade to Backbone 0.5.0+: rename Controllers to Routers, refresh to reset and call navigate instead of save-Location and setLocation. For more details please visit http://documentcloud.github.com/backbone/#Upgrading

6.7 Upgrading to 0.7

Since 0.7.0 brunch uses stitch which comes with a CommonJS modules implementation. Therefore devel-opers have to require modules and export variables and functions explicitly. See an upgrade example here:https://github.com/brunch/example-todos/commit/c57ec1a418b8dcf694185b03a254199217972652

• Update Vendor: remove brunch-0.x.js file from brunch/src/vendor and instead add these files:

– backbone-master.js

– ConsoleDummy.js

– jquery-1.5.2.js

– underscore-1.1.5.js

You can find them by creating a new brunch app in src/vendor.

• Add a config.yaml clone from a new brunch app to brunch/config.yaml

• Update index.html

• Replace all your ‘script’ tags with

<script src="web/js/app.js"></script><script>require(’main’);</script>

18 Chapter 6. Upgrading brunch

Brunch Documentation, Release 1.3.4

• You need to explicitly export everything that needs to be visible in another file. For example a Todo Modelshould change from

class Todo extends Backbone.Model

to

class exports.Todo extends Backbone.Model

• If you want to use any object or function from another module you need to require it. For example if the Todomodel is used in Todos collection you need to add this piece of code to todos_collection.coffee.

{Todo} = require ’models/todo’

• Stitch also compiles templates. So you have to require them as well.

homeTemplate = require ’templates/home’

class exports.HomeView extends Backbone.Viewrender: ->

@$(@el).html homeTemplate()

• Cleanup Directory Structure: remove these legacy files/directories

– brunch/build/web/js/concatenation.js

– brunch/build/web/js/templates.js

– brunch/build/web/js/vendor/

– brunch/config/

– docs/ (keep it in case you still want to use docco manually)

6.7. Upgrading to 0.7 19

Brunch Documentation, Release 1.3.4

20 Chapter 6. Upgrading brunch

CHAPTER

SEVEN

INDICES AND TABLES

• genindex

• modindex

• search

21