sp-build-tasks
👷 SharePoint front-end projects automation and tasks tool-belt

The library was designed for usage with SharePoint Push-n-Pull Yeoman generator but can be used as a stand-alone package as well.
Install
Dependency
npm i -D sp-build-tasks
Integration to the code
// gulpfile.js
const gulp = require('gulp');
require('dotenv').config();
new (require('sp-build-tasks').SPBuildTasks)(gulp, {
privateConf: process.env.PRIVATE_JSON || './config/private.json',
appConfig: process.env.APP_JSON || './config/app.json',
taskPath: './tools/tasks'
});
Settings
Parameter
Description
privateConf
path to credentials config file
appConfig
path to application config file
taskPath
path to custom gulp tasks folder
App config file
The app config file should be a JSON document with the following schema sp-build-tasks/schema/v1/sppp.json
.
The schema represents the following interface:
export interface IAppConfig {
$schema?: string; // Path to `sp-build-tasks/schema/v1/sppp.json`
spFolder: string; // SharePoint relative target folder (e.i. `_catalogs/masterpage/contoso`)
distFolder: string; // Local distribution folder path
deleteFiles?: boolean; // Delete remote files on local files unlink event
masterpagePath?: string; // Path to masterpage .hbs in `./src` structure
masterpage?: any; // masterpage's custom properties passed to hbs template
masterpageCodeName?: string; // masterpage code name (used for renaming output file)
platformVersion?: string; // Masterpage platform version (2016, 2013, etc.)
logoPath?: string; // Path to logo image
bundleJSLibsFiles?: string[]; // Paths to .js files to bundle together in a single vendor.js
bundleCSSLibsFiles?: string[]; // Paths to .css files to bundle together in a single vendor.css
copyAssetsMap?: IAssetMap[]; // Custom static files copy configuration
customActions?: ICustomActionDefinition[];
customStyles?: IAssetMap | IAssetMap[]; // Custom styles
modulePath?: string; // Relative path for module inside dist structure, e.g. `modules/my-module`
customData?: any; // Optional custom data object that can be used for feeding data to templates
webpackItemsMap?: Array<{ entry: string; target: string; }>; // Scripts build configuration. Array or entry/target script pairs.
devtool?: Options.Devtool; // Webpack `devtool` option for development mode, i.e. `eval`
}
Custom Gulp tasks
// `./build/tasks/example.js`
module.exports = (gulp, $, settings) => {
// gulp - Gulp object
// $ - Gulp plugins dynamic loader
// settings - ISPBuilderSettings object
gulp.task('example', cb => {
console.log('Example Gulp Task');
cb();
});
// ...
};
or types supported version:
//@ts-check
const { customTask } = require('sp-build-tasks');
module.exports = customTask((gulp, $, settings) => {
gulp.task('example', cb => {
console.log('Example Gulp Task');
cb();
});
});
Gulp tasks
Authentication config setup initiation
gulp config
Populates ./config/private.json
with credentials options.
Watch and live development
Watch
gulp watch
Watch for changes in ./src
folder, compiles .ts, .hbs and .scss to ./dist
. Watch for changes in ./dist
and uploads to target SharePoint folder.
Watch with SharePoint pages live reload
gulp live
Does the same as the watch
task. Emits files update to SharePoint live reload client which triggers live pages reload for:
JavaScript's updates
CSS's updates
CEWPs updates
Layouts updates
Masterpage updates
Syncronization
Publishing ./dist to SharePoint
gulp push
Publishes all ./dist
folder content to SharePoint target folder.
Publishing in incremental mode
gulp push --diff
Uploads only files which size is different from those in SharePoint.
Fetching files from SharePoint
gulp pull
Downloads all files and folders from remote SharePoint target to ./dist
folder.
Build front-end
gulp build
Compiles front-end to ./dist
folder.
Build options
Production build
gulp build --prod
Used with Webpack build.
Build subtasks
A specific subtasks can be provided as gulp build
parameters:
Parameter
Description
--webpack
webpack'ing .ts to single app.js buldle
--css-custom
bundling custom css (from .scss)
--copy-assets
copying static content
--js-libs
bundling JavaScript libraries
--css-libs
bundling CSS libraries or custom .css
--masterpage
.hbs to .masterpage
--layouts
.hbs to .aspx layouts
--webparts
compiles .hbs CEWPs
gulp build --prod --webpack --webparts
Starts webparts and webpack tasks, also uses production build configs.
Deployment
Live reload
gulp live-reload [--install]
Installs live reload client as ScriptLink custom action to SPWeb.
gulp live-reload --uninstall
Retracts live reload custom action client.
Masterpage
gulp masterpage [--install]
Applies custom masterpage and logo to SPWeb.
gulp masterpage --uninstall
Restores default (seattle.masterpage) masterpage.
Custom actions
gulp custom-actions [--install]
Provisions custom actions from app.json
settings.
gulp custom-actions --uninstall
Removes custom actions based on project namespace prefix.
Configuring CI/CD
Checkout this end-to-end sample.
License
Last updated
Was this helpful?