Categories
static_site_generators

Brunch, the Static site generator

In most web apps, there are two types of pages. One are those just for visitors who are not yet our customers and other belongs to APP which provides the core functionality of the service.

In most scenarios all these non service based content pages are combined into app, hence overloading the app with irrelevant code resulting in slow response time and necessity to update and deploy the app for minor text changes.

One of the best solution to above problem is to separate the marketing / content pages from the actual service. Most the existing application architectures carry too much over head for these simple content pages. For maintaining and developing these content pages we can either go for a full blow CMS like WordPress or use a static site generator which just generates static pages for us and give advanced features like templating, css modules, js modules and js minimizer .

Brunch is one of the static site generators. The main strength of brunch is its simple configuration and convention over configuration approach.

Install brunch

npm install -g brunch

Initiate a new project using

brunch new myawesomepages

It will then initialize the project using bare bones skeleton, which defines the basic structure of how the assets and htmls are to be organized and installs the necessary packages. These are most popular brunch skeletons

* brunch new -s es6 — Super-simple skeleton that does compilation of ECMAScript 6 files out-of-box
* brunch new -s react — Modern skeleton with React library.
* brunch new -s ts — a starter skeleton for TypeScript
* brunch new -s exim — An ultra-lightweight Flux-like architecture for HTML5 apps using Facebook's React library.
* brunch new -s redux — Redux: Predictable state container for React apps.
* brunch new -s marionettejs — Modern skeleton with MarionetteJS library.
* brunch new -s hipster — Ready to Use Skeleton to build Desktop Applications with all the Web goodies of today.
* brunch new -s chaplin — Chaplin, Backbone, HTML5 Boilerplate, jQuery. Perfect for big applications

For the purpose of this tutorial we will use the default skeleton. More can be found @http://brunch.io/skeletons

Now change to the directory run the brunch server

cd myawesomepages
brunch watch -s

which starts its in watch mode, which watches for file changes and updates the build files which our final content pages.

If you inspect the app it has the following structure

├── README.md // Basic readme about the app which you have to customize
├── app //All your code goes here
│   ├── README.md
│   ├── assets // Files inside `assets` would be simply copied to `public` dir.
|   |   ├─ index.html
|   |   ├─ images // place your css background images & other images here
|   |   ├─ fonts // place your web fonts here
│   └── initialize.js 
├── brunch-config.js // the configuration on how to compile pages and brunch plugins configuration
├── node_modules
├── package.json // all brunch dependencies and required libraries are listed here
└── public // The "output" Brunch will re-generate on every build.
    ├── README.md // This was simply copied from our `app/assets` all othe files in assets
    ├── app.js // all js files are combined into app.js which can be customized
    ├── app.js.map // simple source map for debugging purposes
    └── index.html // This was simply copied from our `app/assets` all othe files in assets

Apart from above mentioned directories you can create a vendor  directory which has files that are just copied and combined in app.js without converting them into modules.

All javascript files are combined into app.js  and all css files combined into app.css

A quick peek into the brunch-config.js files gives you the details on how these files are combined

module.exports = {
  // See http://brunch.io for documentation.
  files: {
    // all javascript files are combined to app.js
    javascripts: {joinTo: 'app.js'},
    // all css files are combined to app.css
    stylesheets: {joinTo: 'app.css'},

    // all js template are combined to app.js 
    templates: {joinTo: 'app.js'}
  }
}

All js files are sort alphabetically and combined into app.js.
So to control the order of inclusion you can name the files prefixed with numbers like 001_, 002_, 003_.
Same goes for css files

If you want a different js file for a particular page you can combine using regexes
Lets say we have 001_lib1.js, 002_lib2.js, 003_custom.js and 004_custom2.js js files and lib1 & custom is needed on one page and lib2 & custom2 is needed on another page, you can create different js files like

module.exports = {
  // See http://brunch.io for documentation.
  files: {
    javascripts: {
      joinTo: {
        'app.js': /.*/,
        'page1.js': /^(001|003)_.*js/,
        'page2.js': /^(002|004)_.*js/
      }
    },
    stylesheets: {
      joinTo: 'app.css'
    },
    templates: {joinTo: 'app.js'}
  }
}

Once you are done developing the app, you can generate the html pages using

brunch build -p

Which creates the above htmls, js & css files and minifies them.

Since fonts & images does not need any processing you can create folders called images & fonts in app/assets folder, which are copied as it is to public directory.

Once you are done generating all you have to do is use SFTP / SCP / FTP to upload this directory to the root folder of you website.

Along with this brunch has a boat load of plugins which can help you in using partials, gzip assets, generate digests for assets and create and add cdn to files.

One of the disappointing thing about brunch is that it comes with bare minimum tools, which requires you to spend quite a bit of time to customize it to your taste / best practices using plugins.

It would have been great if it included partial support, asset pipeline (js &css minifying, gzip and cdn) by default.

Overall it is great tool in your repo for creating awesome static sites.