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 <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) 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 <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) • scaffold (generates controller, model & view) Short-cut: brunch g. Examples: • brunch generate model user: would generate file app/models/user.coffee with class User and a unit-test test/models/user.coffee. 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 <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 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 <type> <name> 7 Brunch Documentation, Release 1.2.2 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. • <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.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.