Table of contents
Created
11 September 2012
by Andy Matthews
Requirements
Prerequisite knowledge
A general understanding of the web development and the command line will help you make the most of this article.
User level
Intermediate
It used to be acceptable to write some CSS, HTML and a little bit of JavaScript, upload it to your web server and you had a website. That's no longer the case as people are now hitting your site from a myriad of different devices with names that start with "i", and "Galaxy", and "Nexus". These new devices are fully capable of running the most modern of code but their bandwidth is limited. This places responsible developers in a bit of a quandry. How can you write modern applications while keeping bandwidth usage to a minimum? "Compress your PNG files with XYZ lib from the command line," some people say. "Minimize your CSS," others say and, "Concatenate and lint and uglify your JavaScript." What they don't tell you is how to perform all of those time-consuming actions within the context of your existing development process.
This leaves earnest developers wondering what to do. The marketplace tells you that you must improve the user’s experience, but in today's fast-paced tech companies, taking an extra hour or more of development time just to gain a few speed improvements can be frowned upon. What we need is a tool that will do all of these things for us, while getting out of our way and letting us write code. That tool is here and it is called Yeoman.
What's Yeoman? From the Yeoman website (yeoman.io), Yeoman is "a robust and opinionated client-side stack, comprised of tools and frameworks that can help developers quickly build beautiful web applications." In layman's terms, Yeoman is a series of tools built upon Node.js that performs all of those tedious tasks we mentioned earlier. With just a few commands, Yeoman can create application skeletons, minimize and concatenate your CSS, JavaScript, and compress your images.
Yeoman can fire up a simple web server in the current directory, run your unit tests, and more. Yeoman can help you streamline your workflow by quickly creating Model, View, and Controller boilerplate code for today's most popular JavaScript frameworks. Yeoman can also act as a package manager for many well-known JavaScript plugins and libraries. At the moment, Yeoman is Mac / Linux only, but Windows support is coming soon.
It's easy to get up and running with Yeoman. First, open up a Terminal window. I know the command line may seem scary. I used to be afraid of it myself but Yeoman makes it easy to use. Take look at the following line to install Yeoman. This single command will do everything for you: download, install and configure all in one.
$ curl -L get.yeoman.io | sh
That wasn't so bad was it?
In addition to using Node.js, Yeoman also installs libraries that allow it to compile CoffeeScript files and Sass/SCSS files, as well as a powerful tool called PhantomJS, which allows Yeoman to run unit tests in a headless version (no GUI) of WebKit. Run the command then sit back and let Yeoman set everything up.
While the installation process runs in the background, let’s shift gears for a moment. With any new tool there’s a bit of a learning curve. Yeoman reduces that learning curve by letting you ask it questions anytime you’re not sure of something. If there's a command that you don't understand, just ask Yeoman. If you’d like to know what options a certain command offers, just ask Yeoman. The easiest way to ask for help is just to call for Yeoman. Type the following command and Yeoman will display a list of command line options. Try it.
$ yeoman
In fact almost every command also has its own help option. Ask Yeoman for help for help with a specific command by appending the
--help flag, as in the following:$ yeoman init --help
You can also ask Yeoman for help simply by using the help command:
$ yeoman help
Once the install script is complete, you're ready to use Yeoman. Why don’t you start off by creating an application for your Mom's Bridge Club? They meet once a month and they need a way to post their scores online. Open a Terminal window and create a new folder in the location of your choice, your Desktop for example. The first Yeoman command you run is
yeoman init. It’s the front door to the whole Yeoman ecosystem. Type the following lines into your Terminal window to get started.$ cd ~/Desktop
$ mkdir bridgeclub && cd bridgeclub
Every command you give to Yeoman begins with the yeoman keyword – think of it as asking one of your teammates for help. Start by running the yeoman init command:
$ yeoman init
Yeoman will ask you a series of questions, simply answer yes or no based on your project requirements. For this article, you can answer whatever you like.
Figure 1: Initializing Yeoman
First, Yeoman will ask you if you'd like to include the Twitter Bootstrap styles and plugins, and where you'd like to place them. Next, Yeoman will ask you if you'd like to include RequireJS (for AMD support). You can read more about RequireJS in a recent Adobe Developer Connection article by Aaron Hardy. Finally, Yeoman asks you if you'd like to support writing ECMAScript 6 modules. You can read more about modules in an article by Addy Osmani, ECMAScript 6 Resources For The Curious JavaScripter. After giving you a chance to change your answers Yeoman gets to work.
It’s worth pointing out that Yeoman even offers you a way to skip past all these questions and create an application with just the basics: HTML5 Boilerplate, Modernizr, and jQuery. If that’s more your speed enter the following command you’re off to the races.
$ yeoman init quickstart
After a short while, Yeoman will finish its work and your Bridge Club application will be ready to develop. The project directory now contains a number of files and folders. Let's take a quick look at them all.
Figure 2. Your bridgeclub project after running Yeoman
Starting from the bottom, Yeoman includes a test directory that contains unit tests and spec documentation. By default, Yeoman uses the Mocha test framework to run all of your unit tests, but you can opt for Jasmine instead by passing an additional option to the init command:
$ yeoman init --test-framework jasmine
You can, of course, use whatever test framework you like after Yeoman completes its initial site build. To get a full list of flags for the
init command remember to ask Yeoman for help.$ yeoman init app --help
You'll also find a package.json file which helps you document your application’s author (you of course) and version number. package.json is also used to indicate any dependencies that your app might have on other libraries. Using this file is not required, but it is becoming quite common to have this level of documentation in a single location.
You will also see a directory called app. That directory is where all of the source files for your application are contained: Raw SASS files, Coffeescript, images, original JS files, and more. The app directory is where you write your code and it's where Yeoman pulls from when running its build process (more on that later).
Also notice a file called Gruntfile.js. Yeoman is built on top of another project called Grunt that uses the Gruntfile to indicate configuration options. You can also create your own unique tasks or groups of tasks, or pull from the lengthy list of available Grunt plugins, by adding them to the Gruntfile that every Yeoman project contains. Speaking of tasks, let's run a few to see what they do!
Not every developer uses unit tests, but I bet many of them say they would like to. Until recently, unit testing was a pain to set up and run. But there are so many frameworks to aid you in your testing that it is a crime not to. As mentioned before, Yeoman uses the Mocha framework, which allows for asynchronous testing: perfect for JavaScript and those pesky AJAX calls. In the root of your project, enter the following command.
$ yeoman test
Yeoman fires up an instance of PhantomJS, loads up your test files, then runs them for you, and reports back the successes or failures. You can, of course, still load the tests and run them in a regular browser window, but sometimes you just want to make sure they're passing without seeing all the details. Yeoman helps you do that. Additionally, you could add
yeoman test as part of a longer set of commands, and take action based on the success or failure of your test suite.Yeoman also helps you out in other ways, such as running a local web server in your project directory. You probably have at least a passing familiarity with Apache and vhost blocks, and maybe even adding DNS entries to your hosts file. That's all well and good but it's a pain to do when you just want to quickly check if an AJAX call is working. We all know the browser restrictions on AJAX calls within file:// URLs but running within the context of a web server makes those disappear. It also allows you store your web projects anywhere on your hard drive, and not just within your www or htdocs directories. Tell Yeoman to fire up a simple Python based web server with a single command and run your entire site as if it was in production. Let's try it out right now.
$ yeoman server
Type the above command into your Terminal window and hit enter. After second or two of processing Yeoman lets you know that it's starting a static web server on port 3501. It even opens a browser window with the correct URL for you. That’s great, but Yeoman uses a library called LiveReload to watch your project directory for changes, compile those changes and reload the browser window for you. Let's put the LiveReload feature in Yeoman to the test.
With the Yeoman server still running, browse to the app folder in your project directory and open up index.html in a text editor. Place your cursor anywhere inside the body tag and add some new HTML, then just hit save. You've got to make sure you're watching the browser window because it happens fast. One second your change isn't there and the next it is - all without you having to do a thing. The same is true for JavaScript files, Coffeescript files and even CSS/SASS files. Let's try adding a style. Open up /app/styles/main.css, add the following declaration, then hit save:
body {
background: red;
}
Yeoman doesn’t even reload the browser window for changes to stylesheets. It uses JavaScript to change the stylesheet in the browser. It’s fast too. Change a style, save it, and Yeoman instantly shows the change in the browser window. Reloading the browser window isn't hard, or time-consuming if you're just doing it a few times. But developers like us do it hundreds of times a day, or more. LiveReload courtesy of the LiveReload project, really frees you to make quick changes and see them working immediately. It's a breath of fresh air.
We're not done explaining Yeoman yet. How about finding and installing plugins, libraries or frameworks? Normally, you have to Google for the URL, find the right download link for the correct version of the file, then save it somewhere in your project. If you are hardcore you might get it from the developer's Git repo and compile it. That's cool and all, but with Yeoman you have a teammate who loves helping out. Why not send Yeoman on an errand for the files you need? Yeoman includes a package manager called Bower (built by some of the developers at Twitter). Just give Yeoman a command, and a package name, and it gets that package for you and store it locally. Let's try installing the popular JavaScript application framework Backbone. Enter the following command and watch the magic:
$ yeoman install backbone
Yeoman does two things for you. It downloads the raw source for Backbone into a folder named components in the root of your project. It then moves just the working copy of the file into
/app/scripts/vendor. This way you've got the documentation for Backbone but the full repository isn't clogging up your application's codebase.At some point, all good projects need to launch.Mom’s Bridge Club has been asking when the application will be ready and you don’t have any more time to spend. This is where Yeoman really shines. The build process is complicated and intricate and takes quite some time...for Yeoman that is. All you need to do is type the following command, then go get that Iced Triple Caramel Macchiato you’ve been thinking about all morning.
$ yeoman build
Rather than ask what Yeoman is doing for you here, it's probably easier to ask what isn’t Yeoman doing for you. Remember the Gruntfile we talked about earlier? It contains a list of tasks that Yeoman can execute, and during the build process Yeoman runs every one of them. Yeoman will:
- Run all of your unit tests.
- Lint, concatenate and minify your JavaScript files as well as rev their version numbers if need be.
- Condense all of your CSS files.
- Compress your images.
- Timestamp all your files to prevent browser caching.
- Sift through your HTML files and make sure file references are correct (after concatenation).
After the build process is complete, notice that Yeoman added two new folders to your project root:
temp and dist. The temp folder acts like a cache, containing compiled files which may or may not change again. The dist folder pulls from temp, and contains all of the minimized, compiled, compressed, linted, smothered, covered and chunked application files. This means that you don't have to bother with storing the final files in your repo if you don't want to. It also means that your application is production quality, squeaky clean, and as light and tight as can be. Yeoman is pretty clever isn't it?Yeoman can do much more than this but even if you only use it for the things we talked about here, it is well worth your time. Oh wait...I forgot to mention that Yeoman is free, and open source. Other tools out there do the same thing, some are free, while some cost money. But Yeoman is the only one out there that you can fork and change. If it does something you do not like, change it. If you want to add a feature, write the code for it, then submit it back to the project for everyone else to benefit from.
I hope you've decided to try out Yeoman for yourself. You won't regret it. Additional information can be found at Yeoman.io, github, and their documentation page.
All illustrations courtesy of Leonardo Maia.