SharePoint front-end projects automation and tasks tool-belt

I was highly requested to document SharePoint Push & Pull generator projects' build and configuration process and parameters recently. Despite the fact that the project is open sourced there was real lack of documentation and a lot of things were only in my head.

The generator is the way to combine libraries and settings together and simplify reusability. There are plenty of different libraries and even technologies to make front-end solution build process smooth and easy.

Also, there is some sort of inception of automation layers. A lot of folks know about generator-sppp, a few really know that most of the magic is spelled by a dependency library called sp-build-tasks.

Here we're going to dive into the settings. The article is supposed to be long in some parts it accumulates project's wiki pages.

sp-build-tasks

The library was designed for usage with SharePoint Push-n-Pull Yeoman generator but can be used as a stand-alone package as well.

Recommended usage

Check prerequisites

• Node.js
• NPM or Yarn
• Yeoman
• SPPP Yeoman generator
• TypeScript

npm install yarn yo generator-sppp typescript ts-lint -g  

Create a scaffolder project

Run yo sppp in blank folder for a new project.

yo sppp  

Build options

Build options are a layer of settings which can be defined for a project to set up its unique build workflow.

Settings are stored in ./config/app.json file.

Example setup:

{
  "spFolder": "_catalogs/masterpage/spf",
  "distFolder": "./dist",

  "customStyles": [{
    "src": "styles/frankfurt/frankfurt.scss",
    "dist": "styles/frankfurt.min.css"
  }],

  "bundleJSLibsFiles": [
    "./node_modules/es6-promise/dist/es6-promise.auto.min.js",
    "./node_modules/whatwg-fetch/fetch.js",
    "./node_modules/sp-pnp-js/dist/pnp.js"
  ],

  "bundleCSSLibsFiles": [
    "./node_modules/datatables/media/css/jquery.dataTables.min.css"
  ],

  "copyAssetsMap": [{
    "src": [
      "./node_modules/datatables/media/images",
      "./src/images",
      "./src/scripts/modules/wysiwyg.js"
    ],
    "dist": "./dist"
  }],

  "webpackItemsMap": [{
    "entry": "./src/scripts/module-a.ts",
    "target": "module-a.js",
    "webpackConfig": {
      "cache": true,
      "devtool": "source-map",
      "plugins": []
    }
  }],
  "webpackConfig": {
    "cache": true,
    "devtool": "source-map",
    "plugins": []
  },

  "masterpagePath": "masterpage/frankfurt.master",
  "logoPath": "images/logo.png",
  "masterpageCodeName": "frankfurt",
  "platformVersion": "2016",
  "masterpage": {
    "copyright": {
      "year": "2017",
      "title": "Contoso intranet"
    }
  }
}

Build options: Mapping with SharePoint

Build tools map local dist folder with remote target folder in SharePoint within site assets document library.
_catalogs/masterpage/some_folder is recommended. SiteAssets/some_folder or Style Library/some_folder or others can be used as well.

SharePoint mapping paths are configured in ./config/app.json within the following parameters:

{
  ...
  "spFolder": "_catalogs/masterpage/spf",
    // Publishing SPWeb relative folder path in SharePoint
    // where files should be uploaded to
  "distFolder": "./dist",
    // Local distribution folder with built assets
    // ready for publishing
  ...
}

Build options: Webpack

sp-build-tasks uses Webpack for packing scripts.

TypeScript, ES vNext or vanilla JavaScript can be used as script sources by default.

Webpack settings can be defined in ./webpack.config.js in a usual for Webpack way.
There is a built-in configuration and settings layer.
Webpack build process can be tweaked in ./config/app.json within the following parameters:

{
  ...
  // webpackItemsMap: Array or entry/target script pairs
  "webpackItemsMap": [{
    "entry": "./src/scripts/scriptName.ts",
      // Relative path to .ts, .js file within the project's folder structure
    "target": "scriptName.js", 
      // Relative path to output bundle script within `./dist/stripts` folder
    "webpackConfig": {} 
      // Optional Webpack configuration which is added 
      // to webpack's configs for a specific entry point 
  }],
  "webpackConfig": {},
    // Optional Webpack configuration which is added 
    // to webpack's configs for all entry points
  ...
}

Build options: Custom styles

sp-build-tasks uses SCSS as a language for CSS sources. SCSS files can store raw CSS as well.

SharePoint mapping paths are configured in ./config/app.json within the following parameters:

{
  ...
  // customStyles: Array or a single object element src/dist pair 
  // of source style entry point and output bundle file
  "customStyles": [{
    "src": "styles/frankfurt/frankfurt.scss",
      // Source entry point path
      // relative to './src'
    "dist": "styles/frankfurt.min.css"
      // Output .css file path
      // relative to './dist'
  }],
  ...
}

Build options: JS Libs

Build tools can bundle 3rd party JavaScript libraries.

Libraries' JavaScript paths are configured in ./config/app.json within the following parameters:

{
  ...
  "bundleJSLibsFiles": [
    "./node_modules/es6-promise/dist/es6-promise.auto.min.js",
    "./node_modules/whatwg-fetch/fetch.js",
    "./node_modules/sp-pnp-js/dist/pnp.js"
  ],
  ...
}

It's recommended installing 3rd parties using npm or bower then configuring bundling within the build tools.

Build options: CSS Libs

Build tools can bundle 3rd party CSS libraries.

Libraries' CSS paths are configured in ./config/app.json within the following parameters:

{
  ...
  "bundleCSSLibsFiles": [
    "./node_modules/datatables/media/css/jquery.dataTables.min.css"
  ],
  ...
}

It's recommended installing 3rd parties using npm or bower then configuring bundling within the build tools.

Build options: Assets copy

It's better storing static assets in ./src or other folders, which are the part of the source control system.

Dist folder should be mapped with SharePoint asset folder. Also, the dist folder sometime should not be a part of sources and isn't stored in Git, for example. Aka, temporary folder.

Sometimes 3rd parties, like fonts, should be installed with npm or bower and deployed to SharePoint only partly, e.g. only a specific files out of numerous files of 3rd party package.

Build tools can be configured to copy some static assets in ./config/app.json within the following parameters:

{
  ...
  // copyAssetsMap: Is an array of src/dist pairs opbects
  "copyAssetsMap": [{
    // src: Is an array of paths to folders or files
    // Folders and files are copied based on this array, 
    // subfolders are created automatically
    "src": [
      "./node_modules/datatables/media/images",
      "./src/images",
      "./src/scripts/modules/wysiwyg.js"
    ],
    "dist": "./dist" // Target destination location where files are copied
  }],
  ...
}

Build options: Branding

sp-build-tasks supports branding build automation.

Basic branding settings are tweaked in ./config/app.json within the following parameters:

{
  ...
  "masterpagePath": "masterpage/frankfurt.master",
    // Relative to publishing folder path to custom masterpage
    // Is used in `gulp masterpage:apply` task
  "logoPath": "images/logo.png",
    // Relative to publishing folder path to custom logo
    // Is used in `gulp masterpage:apply` and `gulp logo:apply` tasks
  "masterpageCodeName": "frankfurt",
    // Masterpage code name
  "platformVersion": "2016",
    // Masterpage platform version (2016, 2013, etc.)
  "masterpage": { 
    // Custom structure object which properties 
    // can be used while compiling masterpage's .hbs
    "copyright": {
      "year": "2017",
      "title": "Contoso intranet"
    }
  }
  ...
}

Masterpage sources should be placed in:

• src
  • masterpage
  • frankfurt.2016.hbs
  • frankfurt.2013.hbs

Where frankfurt is a masterpageCodeName sample, 2016 or 2013 parts are platformVersion's.
.hbs is a handlebars, masterpage .aspx's content should be copied to the .hbs initially.

Tasks

Getting tasks list:

gulp --tasks  

By doing this the tree of tasks with dependencies should be rendered in terminal window.

Config

gulp config  

Inits SharePoint credentials prompt wizard.
Wizard is implemented гыштп node-sp-auth-config library.

After config is done, auth settings are dumped to './config/private.json'.

Second run of the task checks './config/private.json' and do not prompt if it exists and all parameters for a specific are auth strategy are provided.

Pull

gulp pull  

Initiates download of all remote assets from spFolder to ./dist folder.
This task can be useful if one is intended to check if the assets in SharePoint had been changed since last publish or in migration scenarios when some assets are already created in SharePoint (with SharePoint Designer, for instance).

Build front-end

gulp build  

Build task combines multiple build actions, such as:

Bundling scripts (typescript, javascript)

gulp build:webpack  

Bundling custom styles from SCSS

gulp build:css-custom  

Copying static resources

gulp build:copy-assets  

Bundling 3-rd party script libraries

gulp build:js-libs  

Bundling 3-rd party styles (CSS) libraries

gulp build:css-libs  

Compiling masterpage template

gulp build:masterpage  

Compiling layouts templates

gulp build:layouts  

Compiling content editor sources webparts

gulp build:webparts  

Publish (push)

gulp push  

Uploads and publishes ./dist folder's content to remote spFolder in SharePoint.
The task uses gulp-spsave for delivering assets to SharePoint.

Watching assets

Standard watch

gulp watch  

Watches local files for changes and initiates build and publishing of changed sources.
The task watches for following sources:
- src - masterpage - [watches masterpage .hbs] - layouts - [watches layouts.hbs files] - scripts - [watches for .ts files changes] - styles - [watches for .scss files changes] - webpartc - [watches for .hbs files changes]

Watch with page live-reload

gulp live  

Does the same as gulp watch, but also emits changed files paths within the live-reload local server.
Implements socket proactive reload using sp-live-reload library.

Deployment helpers

Apply custom masterpage

gulp masterpage:apply  

Applyis custom masterpage to the SPWeb.

Restore Seattle masterpage

gulp masterpage:restore  

Apply custom logo

gulp logo:apply  

Live-reload install

gulp reload:install  

Installs live-reload client script globally on SPWeb as a User ScriptLink custom action.

Live-reload uninstall

gulp reload:retract  

Remove live-reload client script custom action from SPWeb.

Other

TypeScript

Compile

gulp tsc  

Compiles .ts files.

Linting

gulp tslint  

Checks .ts files with TSLint.

Clean

gulp clean  

Deletes ./dist folder.
The task is used as a child in a build process to clean up ./dist before building from sources.

Custom tasks

Just in case if you need do more within Gulp tasks there is a capability of adding add-hoc scripts in './build/tasks' folder. sp-build-tasks reads all JavaScripts in the folder and registers the tasks.

The example of add-hoc task is below:

module.exports = (gulp, $) => {  
    'use strict';

    gulp.task('example', (cb) => {
        console.log('Example Gulp Task');
        cb();
    });
};

Here we're, done with the configuration and build tasks. Now it's time to relax and create something valuable for the portal.
Get ready for automation fun running tasks with understanding how to configure and extend the beast for your own project routines!