Running ngbp on Windows

Josh D Miller has shared ngbp (formerly ng-BoilerPlate), a kickstarter project for getting up and running quickly with AngularJS, build and test tools and a whole other load of awesomeness.  Here, I discuss getting this working on Windows.

I have to say that the tools on offer are exactly what I need to allow me to get the scaffolding out of the way and let me start developing my app. On my latest project, I’ve been considering an AngularJS web front-end, but having .NET services on the back-end. In order to do this, and have a single complete build, I need to develop and deploy on Windows. Josh’s Getting Started documentation is of very high quality, but he does admit to not being interested in supporting Windows developers; below is a quote directly from that Getting Started guide:

“If you’re on Linux (like I am) then throw sudo in front of that command. If you’re on Windows, then you’re on your own.”

While this is understandable (after all, as an open source project you simply can’t keep everyone happy) it did leave me a little hesitant about using ng-BoilerPlate. Therefore, here I’ve detailed the steps I took to not only get ng-BoilerPlate sucessfully running on my Windows development environment, but also to document a few nuggets and nuances I learned along the way.

Pre-requisites

  1. FireFox
  2. git
  3. nodeJS
  4. grunt-cli
  5. Karma
  6. Bower

1. Install FireFox

By default ng-BoilerPlate uses FireFox as the browser for executing JavaScript tests against. You don’t have to use FireFox, and if your project doesn’t call for it, you can skip this step but you will have to alter the list of browsers and launchers in the Next Steps section below.

Alternatively, if you are not restricted by browser policy and are going for high adoption, (i.e. you want as many end users for you application) then not only should you install FireFox, but you should also include other browsers such as Chrome, Safari & IE as part of your compatibility testing. (The Next Steps section below details how this is done.)

Download and install the latest stable version of FireFox from here. Be careful to check the installation options if you don’t want FireFox as your default browser.

2. Install git

If you haven’t already, you will need to install git on your machine for source control. As a Windows guy, I like SourceTree from Atlassian, which can be used as a GUI for git. It also provides the git executable and a batch file (git-cmd) which loads the necessary git folders into the system path to allow you to execute git from anywhere in your filesystem.

Note: if you choose to install SourceTree, the git-cmd batch file should be used to launch a command line window whenever the command line is referred to in the remainder of this post.

Alternatively, if you prefer the power of the command line at your fingertips, then installing the original git client includes git bash; the default command line tool for Windows.

3. Install nodeJS

Download the Windows installer from the  nodeJS site, accepting the default options. This installs nodeJS into your path, which means that it can be executed from anywhere. Just be mindful that nodeJS installs into the AppData folder under your profile which means that you have to ensure that when you use the Node Package Manager from the command line, the command line window is running under the same profile. A simple check of the path will confirm this before proceeding.

4. Install grunt-cli

Grunt is a popular build system for JavaScript/AngularJS apps, and is fundamental to ng-BoilerPlate.  From your command line, install grunt-cli* using the Node Package Manager :

*note: grunt-cli isn’t grunt itself, but the Command Line Interface (CLI) for grunt. grunt-cli simply runs the version of Grunt which has been installed next to the Gruntfile you wish to execute. This allows for multiple versions of grunt to co-exist on the same machine.

5. Install Karma

Karma is the javascript test runner used as part of the build process (automated testing) of ng-BoilerPlate.  Following the same routine, install Karma:

6. Install Bower

Bower is another package manager, but it’s a lot more specialised than the package manager used with nodeJS; instead it is specifically for the web, and developed by Twitter. It’s selling point is that you can pull from web-based source code repositories such as github, with a single statement comprising of the most simple of commands.  (As this detail is not important at this time, but may be useful at a later date when using ng-BoilerPlate, we may revisit this in another post.) To install Bower, follow the same routine as before:

Setting up BoilerPlate

OK, now that you have the pre-requistes for ng-BoilerPlate, you can go ahead and get the ng-BoilerPlate source from here:

Move to your project folder (“project root”), where amongst other files and folders you should see gruntfile.js, package.json and bower.json files. From this directory, execute the following commands to resolve all ng-BoilerPlate dependencies:

At this point you can check that everything is as it should be, by executing the simple grunt command from the command line:

This simple command executes the default task in grunt (i.e. the same as entering “grunt default”).  This default task builds, compiles (lints, minifies) and moves all relevant files to a newly created bin directory at the project root.

On first execution, you may get a Windows Firewall message, like the following one below.

Screen Shot 2014-07-29 at 13.01.43

Ensure the “Private networks, such as my home or work network” checkbox is selected only, and allow access.

What happens next is the beauty and power of the automated tooling you have just invested time installing and configuring; grunt invokes Karma, which executes the automated tests against the configured browsers (FireFox only by default). The FireFox browser will open, splash some Karma text, and then close again. Back at the command line, you will have an indicator of the success (or otherwise) of your tests that have just executed on the browser.

Congratulations! ng-BoilerPlate is now successfully configured.

 

Next Steps

Multiple Browsers

OK, so you have the ng-BoilerPlate components up and running. What next?

Well, you can configure your build to execute your tests against multiple browsers, rather than just FireFox alone. To do this, you have to make the changes detailed in the steps below. For the purposes of illustration, I’ve used Chrome but you can repeat the same steps for IE, Safari, etc.

1. Install Chrome

First of all, you have to install the browser itself, before you can add the plugins and configurations.

2. Install Chrome Plugin

The simplest way to install the Chrome plugin is to execute the following command from the project root:

This not only installs the Chrome launcher plugin for Karma, but adds it to the devDependencies section within the packages.json file, so that it can be included for anyone who gets a fresh clone of your codebase.

3. Update Karma Test Script 

The Karma unit test file (project folder/karma/karma-unit.tpl.js) needs to be edited in 2 places. This first entry will add the Chrome launcher to the list of plugins for Karma to use:

And secondly, this will tell Karma to launch each of the browsers during testing:

Note, this browser entry can be left blank, and instead you can navigate to http://localhost:9018 to save you launching the browser each time.

Continuous Testing

While you can follow the pattern of making and saving changes, execute grunt, observe and repeat, grunt and karma allow you to push things forward a little more.  By issuing the following command:

you are essentially allowing the tools to do your testing in the background with every file save. Not only that grunt watch will simply build the necessary files (minimal tasks required to run the app), and not do the compilation steps such as minifying and linting, saving you time along the way. The build files are then places in a build subdirectory as apposed to the bin subdirectory with the full grunt compilation.

So grunt watch once saves you executing the grunt command every time. Now, this might seem a small win, but its more than just saving you from typing this at the command line each time; its providing you with dynamic and immediate feedback. And that is invaluable and very powerful to JavaScript developers. So, now it’s your turn –  go create something awesome!

 

Summary

Although ng-BoilerPlate is *nix-centric (as with most of the cutting-edge JavaScript frameworks and tools out there) it works just fine with Windows. As it should – it’s just JavaScript after all!

This post hopefully breaks down a few of the nuances along the way for Windows-based developers who want to adopt ng-BoilerPlate.

4 Responses to “Running ngbp on Windows

  • Thanks for the guide. Followed your word and was setup in minutes. I did see an error during the build that looked like this:

    MSBUILD : error MSB3428: Could not load the Visual C++ component “VCBuild.exe”

    However, I just kept plugging away, and at the end grunt ran without any issues. I wonder what that errors was about?

    • headthunker
      2 years ago

      Hey Dave

      I’m glad it helped someone else – double the benefit!
      I’m perplexed by the error you were getting. Are you executing grunt from within an MSBuild script?

  • Awesome giude and the only one I could find so quickly! I ran through word for word three times and come out with a “mssing script: start.” when I try to run “npm start.” I could have missed something else, but after several searches no results. I’ll try looking a bit more, but the help is greatly appreciated.

    • Hi Kyle

      Thanks for the positive feedback.
      I’m not 100% sure where you’re going wrong, mainly because I’m a little confused as to where the “npm start” comes in.
      I’ve mandated installing nodeJS using the installer. If you do that, npm will be available from the command line (under your profile remember).
      From then on, its npm install … all the way.

      If you can give me a clear idea of the steps you have taken to get to this point maybe we can trace from there?

      good luck!

Leave a Reply

Your email address will not be published. Required fields are marked *