Nightly Punk Masters

    sp-build-tasks
    TypeScript icon, indicating that this package has built-in type declarations

    3.19.0 • Public • Published

    sp-build-tasks

    NPM

    npm version Downloads Build Status FOSSA Status Gitter chat

    SharePoint front-end projects automation and tasks tool-belt

    banner

    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 sp-build-tasks --save-dev

    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.

    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.

    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.

    License

    FOSSA Status

    Install

    npm i sp-build-tasks

    DownloadsWeekly Downloads

    9

    Version

    3.19.0

    License

    MIT

    Unpacked Size

    304 kB

    Total Files

    104

    Last publish

    Collaborators

    • koltyakov