Sharepoint Automation with Gulp
Sharepoint Workflows
Typically small scriptlet or widget development requiring only one or two js/css files is done in Sharepoint on the fly. The files are uploaded to a document library in Sharepoint, and then development is easily accomplished by opening the directory directly from a text editor or ide. Alternately, you can keep the relevant document library open in Windows Explorer or on the web, and files can be dragged and dropped whenever changes are made.
For projects only requiring a few files, this is an acceptable (although occasionally annoying) process. A widget that only needs a little bit of handwritten CSS/JS bolted onto a small HTML file doesn’t require any sort of industrial strength deployment pipeline. That changes once we start getting into medium sized projects that come with their own dependencies and complexities. If you want to use a css pre-processor, or bundle your javascript files together, or deploy a whole directory structure at once (or worse, parts of a directory structure) - the manual process or save-as-you-go process can become cumbersome.
Adding Automation
I wanted to automate the entire process involved with moving my files to Sharepoint whenever I make development changes to the documents. To that end, I started looking at the task automation ecosystem.
The two most common choices are Gulp and Grunt. I settled on Gulp for a couple of reasons: One, the task file structures in Gulp more closely mirrored my own thinking and two, I found some great Sharepoint specific libraries that had Gulp integration.
Setting up gulp is easy enough - you just install gulp cli tooling via npm, and then add gulp and a gulpfile to your local directory. Gulpfiles are straightforward to program, and I’ll have some good examples later on in this post.
Sharepoint Deployment
The hardest piece of the puzzle was figuring out how to automatically deploy my files to a Sharepoint Document Library. There are some good resources on MSDN for how to automate file movement, but at a cursory glance it seemed like most of it was aimed at users who want to do document automation from within Sharepoint. Thankfully, I stumbled across the following three libraries which make the next part a breeze.
All three libraries are developed by GitHub user s-KaiNet, and I was just blown away by how quick and easy they were to setup. I encourage you to read through his repositories and get a feel for the code yourself.
node-sp-auth
node-sp-auth is a library that allows unattended http authentication (yes, there are security implications) via nodejs. Critically, node-sp-auth
allows you to select one of a variety of different authentication methods, including oddities like Forms Based Authentication - which I use and therefore require. Sample usage is quite straightforward, as the following demo code shows.
This sample code will return the title of the requested page. I recommend going through the process and attempting to use node-sp-auth
prior to tinkering with spsave
and gulp-spsave
as it is easier to understand & configure the code without additional functionality built around it.
spsave
spsave lets you save files in SharePoint - very straightforward. Once you’ve figured out how to authenticate using node-sp-auth
saving files to SharePoint is a breeze. Example Code:
gulp-spsave
Now we get to the real fun! gulp-spsave is the culmination of the previous two libraries, and combines them to offer easy integration with gulp. Anything you normally do with gulp (sass, browserify, etc.) can be integrated with Sharepoint deployment. Setting a watch on your css directory and then automatically deploying changes becomes as easy as this:
And that’s it! Now, when you run gulp
in your terminal, it will keep an automatic watch on the css
folder in your local directory, and any time there’s a change to a css file in that directory (or a new one is added!) it will detect it and push it to Sharepoint. Pretty nifty!
From here, there’s very little you can’t do. Combine it with as many different gulp tasks as you want and see how quickly you can leverage the power of automation in your workflow.