sp-live-reload - SharePoint pages live reload module for client side development

The module allows arranging live reload capability on SharePoint host pages on frontend assets changing and publishing.

Supported SharePoint versions

• SharePoint Online
• SharePoint 2013
• SharePoint 2016

How to use

Install

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

Demo

Usage withing Gulp task

Watch with live reload (SPSave)

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

let config = require('./config');

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

Watch with live reload (Gulp-SPSync)

For those, who for some reasons prefer gulp-spsync or gulp-spsync-creds over spsave, the following structure is applicable:

const gulp = require('gulp');
const spsync = require("gulp-spsync");
const watch = require('gulp-watch');
const through = require('through2');
const { LiveReload } = require('sp-live-reload');

let config = require('./config');

gulp.task("watch-live", function () {
  console.log("Watch with reload is initiated");
  const liveReload = new LiveReload(config.liveReload);
  liveReload.runServer();
  return watch(config.watchAssets, (event) => {
    console.log(event.path);
    gulp
      .src(event.path, { base: config.watchBase })
      .pipe(spsync(spSyncSettings))
      .pipe(through.obj((chunk, enc, cb) => {
        let chunkPath = chunk.path;
        liveReload.emitUpdatedPath(chunkPath);
        cb(null, chunk);
      }));
  });
});

gulp-spsync has different idiology for the paths. In case of it spFolder in settings always should be equal to "".

Arguments

• siteUrl - SharePoint site (SPWeb) url [string, required]

• watchBase - base path from which files in a local project are mapped to remote location [string, required]

• spFolder - root folder relative (to siteUrl) path in SharePoint mapped to a project [string, required]

• creds - node-sp-auth creds options for SPSave and custom monitoring action provisioning [object, optional for sp-live-reload itself]

• protocol - protocol name with possible values: http or https [string, optional]

• host - host name or ip, where the live reload server will be running [string, optional, default: localhost]

• port - port number [string, optional, default: 3000]

• ssl - ssl parameters [object, required only on case of protocol equal to https]

  • key - local path to key.pem file
  • cert - local path to cert.crt file

creds and spSaveCreds are identical as the modules use the same core authentication module. spSaveCoreOptions can be checked here.

For making initial dive in with the library easier Yeoman generator-sppp is recommended, it has sp-live-reload integrated and creates a scaffolding project with all neccessary setup.

node-sp-auth-config is recommended for building SPSave credential options. See for the example.

CDN scenario

In case of publishing scripts to a CDN (to the different [from SharePoint] domain) raw path should be passed to emitUpdatePath method:

...
liveReload.emitUpdatedPath(rawPath, true);
...

Second parameter equal true, tells emitter to prevent the path value from any local transformation.

By default, the path is transformed from the local one (D:\Projects\ProjectName\src\folder\you_file_path.ext) to a relative SharePoint path (/sites/collection/subweb/_catalogs/masterpage/folder/you_file_path.ext). Where watchBase = ``D:\Projects\ProjectName\src, siteUrl` = `https://sphost/sites/collection/subweb` and `spFolder` = `_catalogs/masterpage`.

HTTPS / SSL

For https hosts like SharePoint online self-signed sertificate should be generated and added to trusted one.

1. Install openssl

• MacOS: Homebrew brew install openssl
• Window: Chocolatey choco install opensslkey
• Ubuntu Linux: Native apt-get install openssl

2. Generate keys

openssl genrsa -out key.pem

openssl req -new -key key.pem -out csr.pem

openssl x509 -req -days 9999 -in csr.pem -signkey key.pem -out cert.crt
rm csr.pem

3. Add cert to trusted

Depending on your client OS, add cert.crt to Trusted root certificates.

• Install certificate
• Local computer
• Trusted root certificates

Manual for Windows.

Installation in SharePoint site collection

Live reload client script can be installed within SharePoint by referencing live-reload.client.js. By default, the path to the client is following: http://localhost:3000/s/live-reload.client.js.

<script type="text/javascript" src="http://localhost:3000/s/live-reload.client.js"></script>

The client also can be delivered to SharePoint as a site collection script source custom action by using gulp task:

gulp live-reload-install

Source:

// ...

gulp.task("live-reload-install", function () {
  console.log("Installing live reload to site collection.");
  var liveReload = new LiveReload(config);
  liveReload.provisionMonitoringAction()
    .then(() => {
      console.log("Custom action has been installed");
    })
    .catch((err) => {
      console.log(err.message);
    });
});

To delete such a custom action another gulp task can be used:

gulp live-reload-unistall

Source:

// ...

gulp.task("live-reload-unistall", function () {
  console.log("Retracting live reload from site collection.");
  var liveReload = new LiveReload(liveReloadConfig);
  liveReload.retractMonitoringAction()
    .then(() => {
      console.log("Custom action has been retracted");
    })
    .catch((err) => {
      console.log(err.message);
    });
});

Usage scenarious

General

Live reload feature during active development stage on DEV environment. The manual monitoring script encapsulation is recommended on a specific page while the process of coding and debugging.

Device-specific

There are cases then a page/view should be running on a specific device, let's say iPad and Safari. For sure, an emulator can be used. But sometimes only the real device can show a behavior. Live reload with shared monitoring server can provide instantaneous reloading feature on a device.