đź‘· SharePoint front-end projects automation and tasks tool-belt
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.
npm i sp-build-tasks --save-dev
// 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'
});
Parameter | Description |
---|---|
privateConf |
path to credentials config file |
appConfig |
path to application config file |
taskPath |
path to custom gulp tasks folder |
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`
}
// `./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 config
Populates ./config/private.json
with credentials options.
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.
Use --skipSync
flag to skip any upload to SharePoint assets, e.g. if you need external tools (like gosip sync) to be used instead of embeded.
gulp live
Does the same as the watch
task.
Emits files update to SharePoint live reload client which triggers live pages reload for:
./dist
to SharePointgulp push
Publishes all ./dist
folder content to SharePoint target folder.
gulp push --diff
Uploads only files which size is different from those in SharePoint.
gulp pull
Downloads all files and folders from remote SharePoint target to ./dist
folder.
gulp build
Compiles front-end to ./dist
folder.
gulp build --prod
Used with Webpack build.
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.
gulp live-reload [--install]
Installs live reload client as ScriptLink custom action to SPWeb.
gulp live-reload --uninstall
Retracts live reload custom action client.
gulp masterpage [--install]
Applies custom masterpage and logo to SPWeb.
gulp masterpage --uninstall
Restores default (seattle.masterpage) masterpage.
gulp custom-actions [--install]
Provisions custom actions from app.json
settings.
gulp custom-actions --uninstall
Removes custom actions based on project namespace prefix.