Brunch Documentation Release 1.2.2 Brunch team June 22, 2012
CONTENTS i
ii
Contents: CONTENTS 1
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 automatically 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 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 output. 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
-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 directory (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 created. 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 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
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 * before: list of files that will be loaded before other files 9
* 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
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
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 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
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
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
Create package.json and config.coffee. You can copy them from new brunch application (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 developers 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. to 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 Model should change from class Todo extends Backbone.Model 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
{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
20 Chapter 6. Upgrading brunch
CHAPTER SEVEN INDICES AND TABLES genindex modindex search 21