sp-live-reload
    TypeScript icon, indicating that this package has built-in type declarations

    4.0.0 • Public • Published

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

    NPM

    npm version Downloads Gitter chat

    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

    Live Reload in action

    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/subwebandspFolder=_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.

    Install

    npm i sp-live-reload

    DownloadsWeekly Downloads

    68

    Version

    4.0.0

    License

    MIT

    Unpacked Size

    230 kB

    Total Files

    23

    Last publish

    Collaborators

    • koltyakov
    • sergeisnitko