Brunch Documentation Release 1.2.2
Brunch team
June 22, 2012
CONTENTS
i ii Brunch Documentation, Release 1.2.2
Contents:
CONTENTS 1 Brunch Documentation, Release 1.2.2
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 new project --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 on localhost: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. brunch generate 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.git and 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-brunch 1.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.2.2
• 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 automatically expanded 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 implementations in 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
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) Short-cut: brunch b. Examples: • brunch b -c ios_config -m: would load ios_config.(js,coffee), build application and minify the out- put.
2.3 brunch watch
Watch brunch directory and rebuild if something changed. Options: • -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 • -c CONFIG_PATH, --config CONFIG_PATH: path to config (default: config)
5 Brunch Documentation, Release 1.2.2
• -m, --minify: minify the result js & css files? Analog of minify option in config file. Short-cut: brunch w. Examples: • brunch w: simply watch current directory & 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: watch current project and run a webserver that would work on public di- rectory (by default). Also, auto-minify files.
2.4 brunch generate
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
6 Chapter 2. Command line API Brunch Documentation, Release 1.2.2
• brunch generate collection user: would generate file app/models/users.coffee with class Users and a unit-test test/models/users.coffee. • brunch generate scaffold news --plural feed: would generate file app/models/feed.coffee with class Feed and a unit-test test/models/feed.coffee.
2.5 brunch destroy
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 be deleted. 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.coffee with class UserList and a unit-test test/unit/collections/user_list.coffee. • brunch d model post -p app/twitter/models: would remove file app/twitter/models/post.coffee with class Post and a unit-test test/unit/twitter/models/post.coffee.
2.5. brunch destroy
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 various aspects 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 by brunch 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, what name should output file have etc. •
* ‘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.2.2
* 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 there is generators.model and you execute brunch generate model twitter_user, brunch will call / load generators.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 AaaBbbCcc model: (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.2.2
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.startServer function. • port: (optional) port on which server will run • run: should the server be launched with brunch watch? Example: server: path: ’server.coffee’ port: 6832 run: yes
3.5. minify 11 Brunch Documentation, Release 1.2.2
12 Chapter 3. Configuration file CHAPTER FOUR
PLUGINS
Brunch uses asynchronous node.js plugins to provide compilation / minification functional.
4.1 Usage
Add “
4.2 API
Brunch language is a CoffeeScript class that has brunchPlugin property. It would be initialized with application config (you can access it by using @config instance variable). • brunchPlugin: (required, boolean) it’s always truthy for brunch plugins. By this field, brunch determines if current 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 time brunch sees change in application source code. Data is contents of source file which will be compiled, path is path to the file and callback is a function that will be executed on compilation with arguments error and result. • getDependencies(data, path, callback): (required in compilers, function) would be called every time brunch sees change in application source code. Used as chain compilation rule. For example, if _user.styl changes and main.styl depends on it, main.styl will be recompiled too. To know this, brunch needs to receive an array of dependent files from the function. * minify(data, path, callback): (required in minifiers, function) would be called every time brunch sees change in application source code. Data is contents of destination file which will be minified, 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.2.2 and result.* onCompile: (optional, function) would be called every time after brunch walks through the whole compilation 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 CSSCompiler brunchPlugin: yes type:’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.2.2
16 Chapter 5. Skeletons CHAPTER SIX
UPGRADING BRUNCH
6.1 Upgrading to 1.2
• Update package.json brunch plugins versions to > 1.0 < 1.3 • Run npm install
6.2 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.3 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 npm install after it. • Upgrade backbone & jquery to latest versions (optional).
6.4 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 generated automatically. Create app/assets if it doesn’t exist. • Upgrade vendor/scripts/backbone-0.5.2.js to vendor/scripts/backbone-0.5.3.js and 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.
17 Brunch Documentation, Release 1.2.2
• 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.5 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.6 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
• You need to explicitly export everything that needs to be visible in another file. For example a Todo Model should 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 Todo model is used in Todos collection you need to add this piece of code to todos_collection.coffee.
18 Chapter 6. Upgrading brunch Brunch Documentation, Release 1.2.2
{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.View render:-> @$(@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.6. Upgrading to 0.7 19 Brunch Documentation, Release 1.2.2
20 Chapter 6. Upgrading brunch CHAPTER SEVEN
INDICES AND TABLES
• genindex • modindex • search
21