- Node and Ruby. (Use homebrew. install command is at the bottom of the page)
- After homebrew install, run
- Verify node installation by entering
which node. If no results, enter
brew install node
npm install -g bower
- The Grunt-cli:
npm install -g grunt-cli
- The Sass-cli:
gem install sass
- If you are going to be making sprites: GraphicsMagick (with homebrew, this should work:
brew install --use-gcc --with-perlmagick graphicsmagick)
-- besides those listed above as requirements --
- Grunt for automation
- Normalize, Sassified as
- Sass along with
- Autoprefixer in the form of
- Scut for mixins and placeholders
- clean-css in the form of
- Modernizr, custom built via
- LoDash, custom built via
- Browserify in the form of
grunt-browserifyfor CommonJS-style modular JS
- UglifyJS in the form of
grunt-datauri-variablesto embed SVGs as datauri's saved as Sass variables
grunt-spritesmith-hdto make retina-ready sprites
- SVGO in the form of
Other Grunt Plugins (for building)
How to Use
Download the files. (Don't bother cloning the repo unless you plan to make changes to the starter repo and commit them.)
npm install to install NPM and Bower dependencies.
If another dev has added a new component to your project via NPM or Bower, you'll need to run
npm install again after pulling the latest repo.
Whenever possible use Bower to install frontend components (documentation here). Then keep them out of the repo.
Most of the files that you'll modify are in
src/. Everything in there goes through some kind of compilation-build-or-copy step and gets output into
public_assets/ for consumption.
Here's the convention we're trying to uphold:
- You should never have to manually modify files within
- You should always be able to completely erase
public_assets/and re-build by simply running
grunt reBuilddoes both parts).
- The site itself should only invoke files within
- We should be able, ultimately, to upload
public_assets/to a CDN.
This command will watch for changes to files, then run the relevant compilation and optimization tasks -- and reload your browser if you have installed the Chrome LiveReload extension. When developing, you probably want to run this.
As part of the build process, the CSS will be minified.
Add Modernizr tests as-needed to the Gruntfile, then run
Add LoDash functions as-needed to the Gruntfile, then run
Use Browserify to write modular JS that compiles into a single file.
But third-party libraries will be left out of the Browserify modules: instead, they'll all be concatenated into a single
libs.js file that the HTML invokes first. This way you can just depend on library globals, as usual, and they can depend on each other for globals (e.g. jQuery plugins).
Because our designers have some GUI optimization apps that are very powerful, we are expecting them to give us PNGs and JPGs already optimized.
However, SVGs will be optimized via Grunt; so svg
src directories there should be
opt versions; and you should only have to modify the
raw folder. The
opt versions will be used by further processes.
SVGs as datauris
This process uses grunt-datauri-variables to transform SVG files into embedded data-URIs stored as SCSS variables.
To do it, add SVG files to
src/images/svg-datauri-assets/raw. As usual, if you're running
grunt watch everything gets taken care of; otherwise, run
The SVG files are optimized into
src/images/svg-datauri-assets/opt, then the variables are output into
src/scss/svg-datauris. Import them into
main.scss and plug them in as background-images.
This process uses
To create a sprite, add files to a folder in
src/images/sprite-assets/ (the folder
all is there by default, if you only need one spritesheet on the site). Multiple folders can be used to produce multiple spritesheets. If you are running
grunt watch, relevant tasks will run automatically; otherwise, run
A spritesheet (or a couple, if using retina-ready functionality) is output to
public_assets/images/sprites/. An accompnaying SCSS stylesheet is output to
src/scss/sprites/. Import this into
main.scss to use the sprites.
In your SCSS, use sprites like this:
@include sprite($[asset's filename]);.
When installing new components with NPM and Bower add
--save-dev to your install command (e.g.
bower install [package] --save-dev). This will ensure that other devs will automatically get the same components when they run
Try to maintain the convention of
public_assets/ when adding new compilation and build processes.