Skip to content

Commit f2fb4e9

Browse files
addyosmaniaddyosmani
committed
Merge pull request #32 from alxhill/master
Added initial content for Brunch chapters
2 parents 0fd6c00 + 62ec71e commit f2fb4e9

File tree

5 files changed

+166
-5
lines changed

5 files changed

+166
-5
lines changed

‎chapters/build-systems/brunch/brunch-topic-1.md

-1
This file was deleted.

‎chapters/build-systems/brunch/getting-started.md

+76-1
Original file line numberDiff line numberDiff line change
@@ -1 +1,76 @@
1-
# Getting started
1+
# Getting started
2+
3+
## *Installation*
4+
The first thing to do is install the ``brunch`` command with ``npm`` by running ``sudo npm install brunch -g``. You'll also want to be using [Bower](http://bower.io) for external packages, which Brunch has excellent support for.
5+
6+
## *Walkthrough*
7+
8+
## Conventions
9+
Brunch has a few conventions that help keep things simple - but you don't have to follow all of them. Firstly, Brunch asks you to specify a folder called 'assets' that is directly copied into your output folder with no modifications. Secondly, most Brunch projects have two separate JavaScript files - app.js, which contains your code, and vendor.js for all external libraries, including bower packages. This allows you to package your files into modules without affecting external libraries.
10+
11+
## Folder structure
12+
In order to understand how best to use Brunch, lets look at a typical folder structure and modify it to follow Brunch's conventions.
13+
14+
The application we'll be converting uses CoffeeScript, AngularJS, and LESS, and has no current build system beyond running the CoffeeScript and LESS watchers on the app/ directory. Here's what the application structure looks like before we install Brunch:
15+
16+
|- app/ # this folder is served statically, with the compiled files living alongside the originals
17+
|-- images/
18+
|-- scripts/ # contains .coffee files, which are converted to .js files by coffee -wc
19+
|--- components/ # components, installed by bower. Currently
20+
|-- styles/ # contains .less files, which are converted into .css files by the less watcher
21+
|-- views/ # angularjs views and templates.
22+
|- index.html # the main app file. Includes <script> tags for every .js file and bower component
23+
|- test/
24+
|- server.coffee # our server file - statically serves the app directory when run.
25+
|- bower.json # bower package folder - still using the old version of bower
26+
|- .bowerrc # bower config file that tells it to install into the app/components folder
27+
|- package.json # npm package folder
28+
29+
30+
The first thing we need to do is modify the application structure to fit Brunch's conventions. That means moving installed packages to outside the ``app/`` directory, and creating an assets folder for static files.
31+
32+
The assets folder will live inside ``app/``. It needs to contain any files that will be served statically - in this case, just ``index.html`` along with the ``images/`` and ``views/`` folders.
33+
34+
For this project, we also had to delete the existing bower configuration file (.bowerrc) and ``components/`` folder, rename the ``component.json`` file to ``bower.json`` before updating bower to the latest version. Running ``bower install`` created a ``bower_components/`` folder in the root project directory. This allows Brunch to easily identify which files are part of our app and which files are external libraries without having to write any complex regular expressions.
35+
36+
Finally, we need to update our index.html to be aware of the changes in structure. Currently, we have this in the head:
37+
38+
```html
39+
<link rel="stylesheet" href="/styles/bootstrap.min.css">
40+
<link rel="stylesheet" href="/styles/main.css">
41+
```
42+
43+
and this in the body:
44+
45+
```html
46+
<script src="/components/jquery/jquery.js"></script>
47+
<script src="/components/lodash/lodash.js"></script>
48+
<script src="/components/angular-unstable/angular.min.js"></script>
49+
<script src="/components/angular-bootstrap/ui-bootstrap-tpls.js"></script>
50+
<script src="/components/angular-sanitize/angular-sanitize.js"></script>
51+
<script src="/components/angular-resource/angular-resource.js"></script>
52+
<script src="/components/angular-cookies/angular-cookies.js"></script>
53+
<script src="scripts/app.js"></script>
54+
<script src="scripts/directives.js"></script>
55+
<script src="scripts/data.js"></script>
56+
<script src="scripts/services.js"></script>
57+
<script src="scripts/controllers/landing.js"></script>
58+
<script src="scripts/controllers/decision-tree.js"></script>
59+
<script src="scripts/controllers/resource.js"></script>
60+
<script src="scripts/controllers/task.js"></script>
61+
```
62+
63+
Ouch! With Brunch, we can replace the css files with this:
64+
65+
```html
66+
<link rel="stylesheet" type="text/css" href="/css/app.css">
67+
```
68+
69+
and the ridiculous number of scripts with this:
70+
71+
```html
72+
<script src="/js/vendor.js"></script>
73+
<script src="/js/app.js"></script>
74+
```
75+
76+
Much better!

‎chapters/build-systems/brunch/introduction.md

+9-1
Original file line numberDiff line numberDiff line change
@@ -1 +1,9 @@
1-
# Introduction
1+
# Introduction
2+
3+
## Brunch's Capabilities
4+
[Brunch](http://brunch.io) is a front end build system that lets you get stuff done with little configuration. Brunch compiles, concats and (optionally) minifies your scripts and styles. It can also package JavaScript files into AMD or CommonJS modules. Brunch automatically applies plugins in the correct order to the right files - so with the right plugins, a .coffee file would be converted into a .js file and automatically minified, with no explicit setup necessary.
5+
6+
## Why Brunch?
7+
Compared to other build tools such as Grunt, Brunch is simple. Grunt's makes very few assumptions about your code or build process, and as such is more flexible in terms of what it can do. However, this flexibility comes at the cost of verbosity.
8+
9+
## *When is Brunch the right choice?*

‎chapters/build-systems/brunch/toc.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
* [Introduction](introduction.md)
22
* [Getting started](getting-started.md)
33
registerTask
4-
* [Brunch - Topic 1](brunch-topic-1.md)
4+
* [Using Brunch](using-brunch.md)
55
* [Troubleshooting](troubleshooting.md)
6-
* [References](references.md)
6+
* [References](references.md)

‎chapters/build-systems/brunch/using-brunch.md

+79
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Using Brunch
2+
3+
## Configuration
4+
Brunch configuration is incredibly simple. Here's a sample ``config.coffee`` file for an AngularJS and CoffeeScript file.
5+
6+
```coffee
7+
conventions:
8+
assets: /^app\/assets\//
9+
modules:
10+
definition: false
11+
wrapper: false
12+
paths:
13+
public: '_public'
14+
files:
15+
javascripts:
16+
joinTo:
17+
'js/vendor.js': /^bower_components/
18+
'js/app.js': /^app\/scripts/
19+
order:
20+
before: [
21+
'bower_components/lodash/lodash.js'
22+
'bower_components/jquery/jquery.js'
23+
'bower_components/angular/angular.js'
24+
]
25+
stylesheets:
26+
joinTo:
27+
'css/app.css': /^app\/styles/
28+
```
29+
30+
(N.B: We're using CoffeeScript here, but you can use raw JavaScript instead if you prefer - just name your file `config.js` instead)
31+
32+
The configuration file is simply specifying what folders Brunch should look for and what it should do with them. So, using regular expressions we tell Brunch that the ``app/assets`` folder should be copied directly into the output folder, which we name ``_public`` (see the `paths` property).
33+
34+
The rest of this is fairly self explanatory, although it's important to note that Brunch uses the new bower.json files to find packages located in ``bower_components`` - so only one of ``jquery.js`` and ``jquery.min.js`` will be included in ``vendor.js``.
35+
36+
Finally, we're also telling Brunch to include certain scripts before others in the vendor.js file, mainly to make sure that ``angular.js`` uses jQuery rather than its jQLite implementation.
37+
38+
## Plugins
39+
Looking at the config file again, you'll notice there's no configuration or 'registering' of plugins - although most plugins can be configured, the default behaviour usually works with no configuration.
40+
41+
Brunch plugins are just npm packages. Any Brunch plugin that's installed will automatically be used. Using ``npm install --save-dev plugin-name`` will install the package and update ``package.json``.
42+
43+
Looking at the ``package.json`` file, we can see the plugins we'll be using in this project:
44+
45+
```json
46+
{
47+
"name": "project",
48+
"version": "0.0.0",
49+
"dependencies": {
50+
"express": "latest",
51+
"mongojs": "latest",
52+
"mongoose": "latest",
53+
"underscore": "latest",
54+
"consolidate": "~0.9.1",
55+
"q": "~0.9.6",
56+
"webshot": "~0.5.1",
57+
"gm": "~1.11.1"
58+
},
59+
"devDependencies": {
60+
"javascript-brunch": ">= 1.0 < 1.8",
61+
"coffee-script-brunch": ">= 1.0 < 1.8",
62+
"css-brunch": ">= 1.0 < 1.8",
63+
"ngmin-uglify-js-brunch": "~1.7.2",
64+
"clean-css-brunch": ">= 1.0 < 1.8",
65+
"auto-reload-brunch": "~1.6.5",
66+
"less-brunch": "~1.5.2"
67+
},
68+
"engines": {
69+
"node": ">=0.8.0"
70+
}
71+
}
72+
```
73+
74+
Here we include the 'base' plugins for JavaScript and CSS, the CoffeeScript and LESS compilation plugins, the CSS minification plugin ``clean-css-brunch``, and the ``ngmin-uglify-js-brunch`` - a plugin that runs JavaScript code through [ngmin](https://github.com/btford/ngmin), the AngularJS 'pre-minifier', then uglifyjs to compress the code. We also use the auto reload plugin, which sets up a web socket server and refreshes the page whenever any files on disk are changed.
75+
76+
## *Workflow*
77+
78+
## *Deployment*
79+

0 commit comments

Comments
 (0)