See other posts on ‘Branding SharePoint sites with yeoman’.
- 👉🏻 Yeoman the web development workflow
- An Introduction to Pug (aka Jade)
- An Introduction to CoffeeScript
- An Introduction to SASS
Through all articles, you’ll see screenshots and commands which I use to get things up and running or to achieve several requirements. I’m doing all my development stuff on a Mac, so don’t be confused everything will also work on Windows. (Of course, I’ve got a virtualized Windows to do my regular SharePoint development…)
Yeoman is built on top of Node.js and uses Git for managing dependencies and loading packages from the web. If you’d like to use Compass within your projects you’ve also to install Ruby and Compass on your development machine. We’re using Compass within out SharePoint related generators, so the final list of dependencies looks like this.
See detailed installation documentation linked behind the dependencies.
Installing Yeoman itself is straight forward. Yeoman is available as Node-Package and can easily be installed by using npm. By executing the following command, Yeoman will be installed on your system.
npm install –g yo
When the installation process is finished, you’ve successfully installed Yeoman with all it’s required tools. So let’s move on and install some Yeoman generators.
Yeoman Generators — The heart of Yeoman
As described in the introduction post, yo is a simple scaffolding tool that is responsible for creating the app structure and providing pre-configured files to get started with development in no time.
Because almost every project is different from another, Yeoman uses generators to describe how a new project will look like.
Most generators are also available as NPM package and can be installed by using the
npm command. Before I install a new generator, it’s an excellent point to get an overview of which generators are currently available.
npm search generator-* you can get a list of all Yeoman generators available through NPM. Alternatively, you can browse the list on Yeoman’s homepage at http://yeoman.io/community-generators.html
Let’s install the most simple generator right now by executing.
npm install –g generator-webapp
Create your first project with Yeoman
Creating projects using Yeoman is straight forward. You have to create a new folder and execute
Append the name of the generator you would like to use.
Alternatively you can execute
yo, and Yeoman will ask you for a generator based on all installed generators. Depending on the generator you’ve chosen Yeoman will ask you some questions about your project. In this example, Yeoman is asking which dependencies you want to add directly to the new project. After selecting, for example, Bootstrap you’ll see the Yeoman magic. Yeoman will dump the project structure and install various dependencies from the web using npm and bower. After downloading the dependencies has finished, it’ll execute the generated
Gruntfile to ‘build’ your web-app. (Don’t care about all details now, we’ll go through them later)
That’s it now your first project has been created by using Yeoman. However, what do we get? Let’s have a closer look at the project directory.
As you can see there are several files and folders created by Yeoman. Most important artifacts are
package.json– This file describes your project and lists all Node.js dependencies such as grunt, various grunt tasks
bower.json– This file is used to manage client-side dependencies and tells bower which libraries it has to install (jQuery, Bootstrap, …)
gruntfile.js– The Gruntfile describes what grunt should do during ‘compilation’ of the project. Depending on the generator you’ve chosen the file may be existing as CoffeeScript file with the name Gruntfile.coffee
testfolder – Put your unit-tests right here
bower_componentsfolder – Bower installs your dependencies right here (will not be stored in git)
node_modulesfolder – NPM installs your dependencies right here (will not be stored in git)
Building the project
To build your project you’ve to start the task inside of the project’s folder as demonstrated here:
Grunt is going to execute the tasks described in your Gruntfile. As a result, you’ll recognize a new subfolder called
dist. Within the
dist folder, you’ll find that’s required for your app to work as expected.
Executing the project
There is also a grunt task for running a small web server serving your project. You have to execute the command.
As you may realize the process stays active and in the background, it’s watching to your source directory. This feature gives you the most significant performance boost. You can now change the HTML of your website, and the files are compiled in the background. You’ll get quick feedback, and you can directly see the results in your browser.
Executing the unit tests
Unit-Testing is built in, so execution is also straight forward. You have to
also, Grunt will explicitly run all tests in your project.
What’s going on behind the scenes
Right now you should have a rough understanding of what Yeoman is offering. You’ve seen how to create a new project and how to build it, how to execute your tests and how to start your project by using grunt. Playing around within your sources and see the changes directly in the browser has also been described in ‘Executing the project’ section. However, now it’s time to see what’s going on. The simple web-app generator generates a both
gruntfile.js. To understand the insights, these are the most critical files.
First, see the list of
devDependencies in the
package.json file. By examining this list, you can understand which tasks are executed when you fire-up grunt build for example. Several tasks such as minifying your images, CSS and HTML are described here. You may also notice the
grunt-contrib-compass reference which will be used to control the powerful compass command directly from your Gruntfile.
Understanding each task may take a while. Therefore you should learn more about GruntJS and the Gruntfile. The GruntJS website offers proper documentation, and it’s also essential to browse the git repositories from all community tasks to see how these tasks can be configured.
When you open up
The copy task configuration
copy: in your Gruntfile, and you should find the following part.
As you can see, each task is configured using a simple JSON object. The complexity of the various tasks differ depending on their level of configuration, but hey JSON is super readable. Don’t be afraid. 🙂
The copy-task has two sub-tasks (
styles). The generator requires two sub-tasks here because other tasks such as
cssmin require to do some further actions with the style sheets. The most complex properties are file-system related. GruntJS offers a great set of wildcard filters to select the files you’re interested in from the file system.
dist sub-task is going to copy all files that match the source pattern (
src) from the current working directory (
cwd) and will copy them into the given destination (
dest). The expand property a unique property! By setting it to
true, you tell the engine that it should build the array of files dynamically instead of defining the files manually. The engine is going to use the combination of all other properties (src, dest, cwd,…).
As you can see, grunt-tasks are very flexible and provide solutions for almost every scenario. Further details see the grunt documentation on http://gruntjs.com or the specific documentation on the grunt-task you’re currently working on. (Almost every grunt task is hosted on github hooray)
Depending on the chosen generator you may have different command line options when executing grunt. These options are also configured within the Gruntfile. The following screenshot shows the “test” and “build” option for the grunt executable. As you can see the option is defined followed by all dependent grunt-tasks that will be invoked in the given order by using grunt.registerTask you can easily create your own CLI or tweak the current configuration. For example, you can easily enable the CoffeeScript compiler by adding the grunt-contrib-coffee package to the project, configure the task as shown with the
copy-task and put it right here in the dependency list.
Installing a package such as
grunt-contrib-coffee is straight forward. Just open a terminal and navigate to the project directory. By executing
npm install grunt-contrib-coffee --save-dev
The package will be installed and added as development dependency (see
package.json). Because Yeoman is using a package called
load-grunt-tasks it’s automatically loaded and available for configuration and execution within the Gruntfile.
Yeoman brings great operations for each developer, and it’s great to see how fast you can develop frontend-apps with the Yeoman stack. I think you get a rough introduction into the topic with this post. Don’t worry if you don’t understand all the insights of Yeoman yet. The easiest way of learning the Yeoman insights is to start at this point and tweak the Gruntfile to fit your needs. Of course, it’s difficult if you come from standard SharePoint development. However, with the rise of the AppModel, we’re finally back to good old web development. Therefore it’s time to catch up with the latest tools and workflows to increase productivity and make SharePoint Apps and customizations popping up quickly.
Within the upcoming posts, we move on with some programming languages and frameworks we’ve backed into our development stack. So keep on reading, and hopefully, you’ll leave your thoughts right here as a comment.