SharePoint client side development with Live Reload

We're getting used to modern SharePoint (client side) development day by day. It transforms into some sort of a hybrid of Visual Studio Code'ing, Gulp tasks, and Chrome Dev Tools debugging and tweaks.

More and more features from the funky front-end development are here at our disposal. Yet, there was one which has been missed and desired by some engineers. You might have heard about BrowserSync, have you? It is a module which can be injected into the page(s) and watches for changes for instantaneous page reload or scripts reload. A developer saves a file in the editor and sees the result applied right away.

As we know, SharePoint has its nuances, which prevents BrowserSync from efficient working. Luckily there is an alternative now.

Recently I've wrapped up the technique we have been using in our team for last months into the NPM module - sp-live-reload.

With sp-live-reload it's possible to save a local client side file, such as javascript, css, html (source for content editor web part) with immediate change in open browsers tabs without a necessity for manual page refresh:

SP Live Reload

To make it work a developer can install the module with use of NPM command:

npm install sp-live-reload --save-dev  

And then use the live reload in Gulp tasks as shown in examples on the project page.

We use it in the combination with SPSave, the module which makes files upload and publishing to SharePoint transparent. Any alternatives will work as well if emitted to the client path is correct.

var gulp = require('gulp');  
var spsave = require("gulp-spsave");  
var watch = require('gulp-watch');  
var through = require('through2');  
var LiveReload = require('sp-live-reload');

var config = require('./gulp.config');

gulp.task("watch-assets", function () {  
    console.log("Watch with reload is initiated.");
    console.log("Make sure that monitoring script is provisioned to SharePoint.");
    var liveReload = new LiveReload(config);
    liveReload.runServer();
    return watch(config.watchAssets, function (event) {
        console.log(event.path);
        gulp.src(event.path, {
            base: config.watchBase
        }).pipe(spsave(config.spsaveCoreOptions, config.spsaveCreds))
        .pipe(through.obj(function (chunk, enc, cb) {
            var chunkPath = chunk.path;
            liveReload.emitUpdatedPath(chunkPath);
            cb(null, chunk);
        }));
    });
});

The most controversial moment is how to deliver a live reload client script to SharePoint. Some possible issues are connected with that. As the environment can be shared between different persons.

There are following assumptions taken in mind:

  • Live reload is actual in a development environment (less on a test, and almost never on the production)
  • There are limited developers on a specific development environment to conflict with each other
  • There is a variety of different browsers which should be supported by the reloading module

With this being said, let me describe the approach:

  • There are two options for delivering live reload client script to SharePoint:
    • Manual, when watch task is running it provides a URL to the script
    • Automated, a special gulp task exists for provisioning user custom action with script source
  • Live reload script references for a localhost running server to receive information about updates, a developer who aren't running live reload task and doing something in the console just see one 404 error for a page load (this bothers me a bit, but it's possible to live with that)
  • Custom action can be easily retracted with another gulp task after the development session is finished to avoid any hassles
  • When two or more developers are "live watching" on the same site collection only one custom action is created, so all developers should share the same settings for the protocol and port, use default if possible

A few words about the architectural implementation. Client and watch server use Socket.io as a transport layer. All the browsers which are supported with Socket.io and SharePoint are automatically supported for live reload.
The live reload server is running inside some watching task (gulp or other), on change and deliver events the server emits the message with the relative path for the resource in SharePoint which has been updated.
The live reload client receives the messages from the server and checks if any resource is on the page. The client takes in mind SharePoint related features, like CEWP's source content. Also, there will be a support for a masterpage update and page layout update detection. As well as a community voice, as the module is extendable and open sourced.

Live reload works with On-Premises SharePoint installations (2016 and 2013) and SharePoint Online. Yet with SharePoint Online or any running over HTTPS some additional afford is needed to generate SSL certificate and add import it to trusted. But it worth it!

sp-live-reload also is integrated into generator-sppp so you can use Yeoman generator to check it in action.