Kickstart Your Project With INIT And Grunt

As is customary in the open-source world, you can extend Yeoman any way you like, modifying the available generators to your needs. But what exactly would you put in a custom generator? Have you thought about a good workflow and about which tools provide the most convenience?

Introducing INIT

First, allow me to introduce INIT. Based on the popular HTML5 Boilerplate project, INIT adds modern tools — such as Sass, Grunt, RequireJS and Karma (for automated testing) — and is easy to customize and extend. You no longer have to worry about those few things that you have to do manually — or that you forget to do at all.

INIT is a set of tools that provide a sensible workflow and structure on which to base your Web projects.

You no longer have to copy a project’s default files or download dependencies that you use in most projects, such as jQuery, Modernizr and Normalize. INIT works on Mac OS X, Windows and Linux and supports all major browsers, including Internet Explorer 8 and nearly all mobile browsers.

INIT also provides a staging workflow. As you develop a page, you’ll want to refer to unminified CSS; after deployment, however, you’ll want to point to the versioned, minified CSS file; this project takes care of that. It also acts as a static file generator because it supports HTML concatenation out of the box.

For more details on INIT’s workflow philosophy and set of features, see The Nitty Gritty’s “Reducing Boilerplate Code in Front-End Projects.”

INIT has a slightly different set of helpers than Yeoman’s Web app generator, including a workflow structure that is easy to extend and customize.

While Yeoman’s Web apps conduct simple testing, via Mocha and PhantomJS, INIT uses the more capable Jasmine test suite and Karma to run tests. INIT doesn’t expect you to need CoffeeScript, Compass or LiveReload, so it doesn’t install those by default. But should you need them, you can easily add them via plugins.

INIT does require a few dependencies to be installed on your machine:

• Node.js The technical foundation of Grunt
• Bower To manage front-end dependencies
• Grunt.js and Grunt CLI To run INIT tasks

Git is also recommended as a versioning system. To set up a new instance of INIT, grab the project’s code, extract the archive, and run the following in your command line:

git init
npm install -g grunt-cli
npm install
git add .
git commit -m ‘Initial commit’

This will install everything you need to run the Grunt tasks automatically. It will also create a components folder that holds all vendor dependencies managed by Bower.

Installing INIT in the command line

Now that INIT is installed, we can take a closer look at what it brings to the table.

Folders, Files And Build Strategies

We can divide the file structure into four parts: configuration files, development files, tests, and the folder for the ready-to-use distribution files.

Configure Your Editor And Code Settings

INIT sets up some decent guidelines to ensure that your code is consistent. The principal settings for the code editor are configured in the .editorconfig file:

[*]
end_of_line = lf
indent_style = tab
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true


[.htaccess]
indent_style = space
indent_size = 4

[*.json]
indent_style = space
indent_size = 2

Choose whether to use tabs or spaces for indentation, the character set, and the end of line style for the various file types. INIT has common defaults but can be easily adapted. If your editor recognizes EditorConfig files, then those configurations will be applied to your project automatically. The EditorConfig file is supported via a plugin in such apps as Sublime Text, WebStorm, Vim, Emacs, TextMate and more; a full list and links can be found on the official website.

INIT configures a few other things, too. For example, the .gitignore file contains all of the directories and files that should be excluded from Git versioning, and the .jshintrc file contains all of the rules that should be applied when JSHint tests your code.

Finally, the .htaccess file includes Apache Server Configs. If you use another server, please check the official repository maintained by H5BP. The server configuration file can reduce bandwidth by sending out Gzip’d files to the client and by setting cache headers so that files are cached in the browser. It also configures security settings to safeguard your website from common attack vectors.

Lastly, you can set up redirects for your domain, which is incredibly useful for preventing duplicate content from appearing in search engines and for when you change the website’s domain.

Configure the Automated Helper Tasks

When talking about automated tasks earlier, I mentioned Grunt. It automates tasks that you usually run manually during the development phase of a project. The following are some of the tasks built into INIT:

• JSHint and RequireJS
• Sass parsing
• Modernizr custom build
• Image optimization via ImageMin
• Concatenation, minification and versioning of files
• Karma unit tests

Plenty more may be added to a project; INIT just provides the most useful and frequently used tasks to save you time. The official documentation contains a demonstration of how to add LiveReload and SVG-Min as tasks. A couple of other official plugins will save you even more time.

The Build Process

To use all of these tasks and benefit from the tools, you can run a couple of predefined Grunt tasks in the command line. These Grunt commands run several subtasks that we can use to build the page or run unit tests:

• grunt dev This checks your JavaScript code through JSHint, compiles the Sass files and builds your static pages.
• grunt build This optimizes images, creates a custom Modernizr build and runs Karma tests, among other things. This is the task you use to generate the production files.
• grunt travis This runs unit tests via Karma in your continuous integration tool (in our case, Travis CI).
• grunt watch This runs the dev task every time you save a source file, so that you don’t have to constantly switch between browser, editor and command line.

The terminal will tell you whether something has gone wrong, like whether the JavaScript has a syntax error or Sass couldn’t find a mixin.

Automated Tests: Make Sure You’re Doing It Right

The sooner you find an error, the cheaper it will be to fix. All of us at some point have spent at least half an hour hunting down a missing comma or trying to figure out why that one CSS property doesn’t work. These manual tasks could be done much more quickly by little programs.

JSHint, for instance, complains when we screw up JavaScript syntax by checking against common rules. Jasmine enables us to write unit tests to verify code. Karma runs those tests in the browser.

These automated unit tests ensure that the code works fine. While they don’t replace manual testing by you, they do add a layer of quality assurance and save you time by reporting problems as soon as they are introduced. There are almost no limits to writing unit tests. To learn about writing advanced unit tests, read Guido Kessels’ article “Advanced Unit Testing Techniques in JavaScript”.

By default, INIT uses Jasmine as a test engine and uses Karma to run tests, which are both easier to handle than Mocha. But if you don’t like Jasmine or Karma, you can use any other tool that has a Grunt task.

Static Website Generator

A small static website generator is built into INIT by default that you can use right away.

In pages.json, you can set up the HTML files to generate. The pieces used to construct those files are usually stored in the templates directory. To tell INIT how to assemble things, you would declare a target, name its source pieces and specify a file to save the result to:

{
  “index”: {
    “src”: [
      “templates/header.html”,
      “templates/index.html”,
      “templates/footer.html”
    ],
    “dest”: “temp/index.html”
  }
}

So that you don’t have to start from scratch, INIT comes with a preconfigured index.html file that you can customize.

This system enables you to work with multiple distinct files, which in the end will make up the HTML that you view in the browser. This is handy if you’re creating multiple files that all use the same header, footer and navigation. You can share content between the “static” pages without having to maintain duplicate files.

Customize!

INIT gives you a solid tool set to start projects more efficiently. It optimizes images and minifies code so that you don’t have to worry about those tasks.

But while it is a solid starting point for new projects, I encourage you to adapt it to your habits and coding workflow. If it’s missing some tools you like, add them; if you don’t need some tools that it does have, remove them. Adapt it to be your ideal framework.

I’ve used INIT for some large projects and use it now for most of my projects, configuring it to what I (and the development team) actually need, which varies from project to project. The static file generator makes it easy for me to work independently of the back-end team, while still being able to show clients my progress right in the browser.

An Outlook

We are working on a number of plugins to extend INIT’s feature set. You can find the plugins on GitHub.

INIT is not meant to replace Yeoman. In fact, you can use INIT via Yeoman. A Yeoman generator is available — generator-init — so you can simply build your own INIT instance using npm install -g yo and npm install -g generator-init.

I’d love to hear feedback, feature requests, ideas and insights on how you use INIT. Please let me know here in the comments, or file a bug in GitHub.