Tags

, , , ,

I have used Yeoman from time to time and it really is a nice tool if you can find the right generator. Yeoman, if you are not familiar with it, is a scaffolding utility that can help setup just about any type of project.  For example: want to create a jQuery plugin? Just use the official jQuery generator and it will setup the entire structured for you, ready with testing framework and Grunt build configuration. There are generators for just about any type of project. If you kick off different projects on a regular basis, its worth looking into Yeoman and how it can support you in starting a new project.

I normally did this by maintaining my own set of folders that contained the setup I liked for different project types.  This works, but it still requires some tedious manual changes every time I copy a folder to start a new project – things like:

  1. Change App/Library name across several files
  2. Add/Remove dependencies as needed
  3. Adjust build steps
  4. etc.

Yeoman, however, can do all this after prompting you for a few values, and it comes setup to take advantage of npm and bower, which makes it ideal for setting up browser based projects.  Wanting this type of flexibility, I took my setup for creating SharePoint Single Page Applications (SPA) and converted that to a generator – now found here: github.com/purtuga/generator-sharepoint-spa.

Usage

First, you need to obviously have yeoman installed:


npm install -g yo bower grunt-cli gulp

Now, let’s install the generator so that yeoman can use it:


npm install -g generator-sharepoint-spa

Ok. Now we’re all setup to create our first SharePoint SPA project based on this generator. Lets create a new folder and then execute yeoman inside that folder.


mkdir mySpApp

cd mySpApp

yo sharepoint-spa

The generator will ask a few questions, including weather a few libraries should be included as part of the setup:

generator-sharepoint-spa

When the interview process completes, Yeoman will proceed to setup the directory and file structure for the app, and then run both npm install and bower install, leaving your directory ready to go.

The App Structure

The structure that is created looks like the following:

generator-sharepoint-spa-app-dir

app Folder:

This is where your your application runtime code live. The folder is setup with a scripts and styles folder where your JavaScript code and CSS style sheets should live. The vendor folder is created by bower.js to install the dependencies that have been defined for your app. The content of this folder should not be manipulated outside of the bowser.json configuration file (note that this folder is included in the GIT ignore file and thus will not be included/saved with your commits).

The scripts folder contains a SharePoint app initializer (init.js) as well as an application main module (main.js), which serves as the entry point into the application. All files (with the exception of init.js) are AMD modules and any new module created should also be defined as such.

The styles folder contains a common style sheet by default (common.less) and is setup to use the LESS CSS pre-processor from within the AMD modules (just take a look at the main.js module).

setup Folder:

The setup folder has several files used by the build process to create both the “compiled” single-file web app as well as a development version that utilizes requireJS as the AMD script loader.

_build Folder:

The build folder is created by the (Grunt) build process and is where you will find the built app along with a single-file compiled version of the app called app.run.aspx and app.debug.aspx (includes non-minimized code).

About The Build

The build for the project is handled by Grunt. The primary tasks available are:

  1. build : Will build the problem, but not the single-file application.
  2. deploy : Builds the project and then copies the files from the _build folder to a designated folder (ex. a SharePoint folder that is currently being synced to your OneDrive for Business local folder).
  3. spa : Will build the project and create the single-file compiled versions (app.run.aspx and app.debug.aspx)
  4. jshint : validate our code with jshint
  5. watch : Validate your code with jshint as files are saved

Example

To play with a test app I created, that shows how easy MyBoard (a Task Manager app I also created) is to install, take a look at this: github.com/purtuga/SPLightBoard. The App’s compiled single-file is located under the dist folder.

What’s Missing or Whats Next

The current setup will get you up and running with creating small apps that can be quickly deployed to SharePoint.  The setup of third party libraries needs some more attention in future versions, since currently only SPWidgets (full disclosure: my own creation) is integrated into the Require.JS setup and build process – mainly because its currently the only one I list that is AMD compliant… SPServices is making the move, but has not yet release a version that supports it and SharePointPlus does not offer such support (as of this writing).

I’ll also be making changes at some point to provide a way to efficiently add jQuery/jQuery UI and require.JS support, that takes into consideration any existing versions of these libraries that may already be loaded (a common problem with SharePoint environments is that every tries to load their own version of these libraries without first checking if they are already available).

Lastly, the generator does not currently provide a setup for running unit tests, although a test folder is created during setup. My goal here is to provide a menu allowing you to choose a testing framework and then re-use existing generators to add the setup.

Conclusion

Yeoman generators make setting up new projects a breeze and I’m glad I went through the effort of converting this SharePoint SPA template I had. Setting up new SharePoint web apps is now an effort that takes only a few-seconds.