Brunch DocumentationRelease 1.0.0

Brunch team

June 22, 2012

CONTENTS

i

ii

Brunch Documentation, Release 1.0.0

Contents:

CONTENTS 1

Brunch Documentation, Release 1.0.0

2 CONTENTS

CHAPTER

ONE

DIRECTORY STRUCTURE

1.1 Simple (included with brunch)

config.coffeeREADME.md

/app//assets/index.htmlhumans.txtimages/

collections/models/styles/routers/templates/views/initialize.coffee

/build/ (generated by brunch)index.html (copied from app/assets)scripts/app.js (compiled & compressed)

styles/app.css (compiled & compressed)

images/ (copied from app/assets)/test/

functional/unit/

/vendor/scripts/backbone.jsjquery.jsconsole-helper.jsunderscore.js

styles/normalize.csshelpers.css

• config.coffee contains configuration of your app. You can set plugins / languages that would be used here.

• app/assets contains images / static files. Contents of the directory would be copied to build/ withoutchange.

• Other app/ directories could contain files that would be compiled. Languages, that compile to JS (coffeescript,

3

Brunch Documentation, Release 1.0.0

roy etc.) or js files and located in app are automatically wrapped in module closure so they can be loaded byrequire(’module/location’).

• build is generated automatically, so you don’t need to put anything there.

• test/ contains feature & unit tests.

• vendor contains all third-party code. The code wouldn’t be wrapped in modules, it would be loaded instantlyinstead.

4 Chapter 1. Directory structure

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

• -o DIRECTORY, --output DIRECTORY‘: build path

• -t PATH_TO_TEMPLATE --template PATH_TO_TEMPLATE: path to project, contents of which willbe copied to new .

Short-cut: brunch n.

Examples:

• brunch new twitter -o twitter: would create twitter/ directory and create new brunch projectthere.

• brunch new twitter -t ~/brunch-templates/simple

2.2 brunch build

Build a brunch project. Options:

• -o DIRECTORY, --output DIRECTORY: build path

Short-cut: brunch b.

Examples:

• brunch build -o .: would build application and place results to current directory.

2.3 brunch watch

Watch brunch directory and rebuild if something changed. Options:

• -o DIRECTORY, --output DIRECTORY: build path

• -s, --server: run a simple http server that would server output dir

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

5

Brunch Documentation, Release 1.0.0

Short-cut: brunch w.

Examples:

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

• brunch watch --output . --server: watch current directory, compile the output to current direc-tory and run a webserver that would work on current directory.

• brunch watch --output /tmp --server --port 8841: watch current directory, compile theoutput to /tmp and run a webserver that would work on /tmp on port :8841.

2.4 brunch generate <type> <name>

Generate model, view or route for current project. 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 be cre-ated. Useful if you prefer non-standard directory structure.

Short-cut: brunch g.

Examples:

• brunch generate collection user_list: would generate fileapp/collections/user_list.coffee with class UserList and a unit-testtest/unit/collections/user_list.coffee.

• brunch g model post -p app/twitter/models: would generate fileapp/twitter/models/post.coffee with class Post and a unit-testtest/unit/twitter/models/post.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.

6 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 buildPath

Optional, string: sets directory which will contain files, generated by brunch build or brunch watch.

Default value is ’public’.

Examples: ’../../deploy’, ’build’, ’/Users/john/web’.

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

* 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:

7

Brunch Documentation, Release 1.0.0

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 framework

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

Default value is ’backbone’.

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

3.4 minify

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

Default value is false.

Examples: true, false.

3.5 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.runServer function.

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

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

Example:

8 Chapter 3. Configuration file

Brunch Documentation, Release 1.0.0

server:path: ’server.coffee’port: 6832run: yes

3.5. server 9

Brunch Documentation, Release 1.0.0

10 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.

• minify(data, path, callback): (required in minifiers, function) would be called every time brunchsees change in application source code. Data is contents of destination file which will be minified, path is pathto the file and callback is a function that will be executed on compilation with arguments error and result.

Example:

CSSCompiler would simply read the file and return its contents.

11

Brunch Documentation, Release 1.0.0

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

12 Chapter 4. Plugins

CHAPTER

FIVE

UPGRADING BRUNCH

5.1 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).

5.2 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.

5.3 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

13

Brunch Documentation, Release 1.0.0

– 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

5.4 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>

• 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/

14 Chapter 5. Upgrading brunch

Brunch Documentation, Release 1.0.0

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

5.4. Upgrading to 0.7 15

Brunch Documentation, Release 1.0.0

16 Chapter 5. Upgrading brunch

CHAPTER

SIX

INDICES AND TABLES

• genindex

• modindex

• search

17