Using Gulp, Watch, and SP-Save to speed up SharePoint Branding Development
How would you like to be able to edit branding files locally on your machine (not through Windows Explorer to SharePoint), make that your local path for TFS for proper source control, and have your changes immediately sync to SharePoint on premises or in the cloud for testing? This is the story of how we achieved that, and how you can easily integrate that into your own development processes.
I'll start by describing the end result, then our journey that got us there, and end with what you need to use this yourself.
The best way to get an understanding of how this works is to watch the short video below.
I've been playing with SharePoint Framework (SPFx - https://dev.office.com/sharepoint/docs/spfx/sharepoint-framework-overview) for about a year now. When I first started I found it somewhat overwhelming as it was a completely new development environment for me coming from the traditional .NET and Visual Studio I was used to. However, we were already transitioning to client-side development, and SPFx seemed to align very well with that.
The client side tools for SPFx are built on Node.js (https://nodejs.org) and Gulp (http://gulpjs.com), among others. Microsoft has really embraced the open source world. Once I got my head around using Gulp for the build processes, the power and shortened development cycle really appealed to me. Using the gulp-watch package (https://www.npmjs.com/package/gulp-watch) any changes made in your SPFx project locally are built and immediately deployed to the runtime environment. You then just refresh your browser, and see your changes right away. No more build, deploy, wait, test, and repeat long cycles. Literally in seconds you can make a change and see the results.
I started thinking about how this could be applied to any client side SharePoint project. In particular, branding projects tend to have css, js, master page, display templates, page layouts, and html files associated with them. We've typically opened the SharePoint master page gallery in Explorer (which is painful to get to work sometimes) and edited there. The problem is we typically like to see full dev, test, and prod environments, and we need to move files between them. We've got PowerShell scripts down pat to do that (see our www.envisionit.com/shakespeare project for details on that), but it depends on having up to date files in our Team Foundation Server source code repository. Yes, we can copy from SharePoint to TFS, but we would often forget, and changes would get overwritten. We needed a better way.
A big thank you to Marc Anderson (http://sympmarc.com/) and Julie Turner (http://julieturner.net/) for their assistance with this. We chatted several times back in the fall, and Julie walked me through their approach and my challenges getting it working for me. In particular, they pointed me at the gulp-spsave plugin (https://www.npmjs.com/package/gulp-spsave) for saving files up to SharePoint (on premise or online).
There were a few improvements we have implemented on the approach Marc and Julie took, as did a number of other blogs I found. The first was that credentials (including passwords) were stored in the config files. That's a big no-no for me, as I don't want to see credentials in source code, TFS, and ultimately passed around to clients and others. The other is the detection for changed files. Most approaches use gulp-cache to build a local cache to compare and see which files have changed. The problem is the first time you run it on a new machine, the cache is empty so it copies every file to SharePoint. That may be a large number of files, and could overwrite other work in progress when there are multiple developers.
The first problem of credentials was fairly easy to solve; we just added code to prompt for credentials in the script when it is first run. It's an extra step, and maybe we could get Windows Authentication to deal with some of the scenarios, but for now it works. The second one took more work, but eventually we got it the way we wanted by switching to the change event in our watch task, which fires for each changed file.
Implementing into Your Project
So how does this work? It's pretty straight forward, and here's the components.
|gulpfile.js||Main script that drives the process|
|InstallGulp.cmd||Batch file for installing the NPM packages|
|package.json||Package file that describes the various Gulp add-ins required|
|RunGulp.cmd||Executes the gulpfile.js to start watching and uploading files|
To implement this into your project follow these steps:
- Create a local project folder
- Download the EIT-SPSave.zip archive and extract it to the project folder
- Create a sub-folder to contain the various branding files
- Install the Node.js LTS version from https://nodejs.org/en/
- Open a command prompt
- Install Gulp globally on your system by running the following command
- npm install -g gulp
- Launch InstallGulp.cmd to run npm install and download and install the required packages
- Update the settings.json with your project-specific configuration
Once it is implemented on your local machine, simply follow these steps when editing branding files.
- Ensure that your local files are up to date from your Source Control
- Run the RunGulp.cmd to start the watch process
- Enter your credentials
- Edit and save your branding files
- Confirm that your RunGulp window shows that the updated files are being uploaded to SharePoint
- Refresh your browser session against SharePoint
- Confirm your changes
- Repeat steps 4-7 as required