Integrate gulp tasks in SharePoint Framework toolchain

SharePoint client-side development tools use gulp as the build process task runner to:

  • Bundle and minify JavaScript and CSS files.
  • Run tools to call the bundling and minification tasks before each build.
  • Compile LESS or Sass files to CSS.
  • Compile TypeScript files to JavaScript.

One common task you can add to the SharePoint Framework toolchain is to integrate your custom gulp tasks in the build pipeline.

Gulp tasks

Normally gulp tasks are defined in the gulpfile.js as:

gulp.task('somename', function() {
  // Do stuff

When working with the SharePoint Framework toolchain, it is necessary to define your tasks in the framework's build pipeline. After the task is defined and registered with the pipeline, it is added to the toolchain.

SharePoint Framework uses a common build toolchain that consists of a set of npm packages that share common build tasks. Hence, the default tasks are defined in the common package as opposed to your client-side project's gulpfile.js. To see the available tasks, you can execute the following command in a console within your project directory:

gulp --tasks

This command lists all the available tasks.

Available gulp tasks

Custom gulp tasks

To add your custom tasks, define the custom tasks in the gulpfile.js.

Open the gulpfile.js in your code editor. The default code initializes the SharePoint Framework toolchain and the global gulp instance for the toolchain. Any custom tasks added should be defined before initializing the global gulp instance.

Add your custom task

To add your custom gulp task, add a new subtask to the SharePoint Framework build pipeline by using the build.subTask function:

let helloWorldSubtask = build.subTask('log-hello-world-subtask', function(gulp, buildOptions, done) {
  this.log('Hello, World!');   
  // use functions from gulp task here  

In the case of a stream, you return the stream:

let helloWorldSubtask = build.subTask('log-hello-world-subtask', function(gulp, buildOptions, done) {
  return gulp.src('images/*.png')

Register your task with gulp command line

After the custom task is defined, you can register this custom task with the gulp command line by using the build.task function:

// Register the task with gulp command line
let helloWorldTask = build.task('hello-world', helloWorldSubtask);


Any custom tasks added should be defined before initializing the global gulp instance, that is, before the following line of code: build.initialize(gulp);

Now you can execute your custom command in the command line as follows:

gulp hello-world


You cannot execute the subtask registered by using the build.subTask function directly from the command line. You can only execute the task registered by using the build.task function.

Execute your custom task before or after available tasks

You can also add this custom task to be executed before or after certain available gulp tasks. The following gulp tasks allow you to inject your custom task before or after the task:

  • Generic build task (that consists of all the available tasks)
  • TypeScript task

The SharePoint Framework tasks are available in the default build rig. The build rig is a collection of tasks defined for a specific purpose, in our case, building client-side packages. You can access this default rig by using the build.rig object and then get access to the pre- and post-task functions:

// execute before the TypeScript subtask

// execute after TypeScript subtask

// execute after all tasks

Example: Custom image resize task

As an example, let's use the image resize gulp task. It's a simple task that allows you to resize images.

You can download the completed sample at samples/js-extend-gulp/.

In the image resize task's documentation, it shows how to use this custom task:

var gulp = require('gulp');
var imageResize = require('gulp-image-resize');

gulp.task('default', function () {
      width : 100,
      height : 100,
      crop : true,
      upscale : false

We use this information to add this task in our project by using the build.subTask and build.task functions:

var imageResize = require('gulp-image-resize');

let imageResizeSubTask = build.subTask('image-resize-subtask', function(gulp, buildOptions, done){
    return gulp.src('images/*.jpg')
                   width: 100,
                   height: 100,
                   crop: false                   
               .pipe(gulp.dest(path.join(buildOptions.libFolder, 'images')))

let imageResizeTask = build.task('resize-images', imageResizeSubTask);

Because we are defining the stream, we return the stream in the build.subTask function to the build pipeline. The build pipeline then asynchronously executes this gulp stream.

Now, you can execute this task from the gulp command line as follows:

gulp resize-images


You also see this resize-images task in the available tasks for your project when you execute gulp --tasks:

image-resize-task with available tasks

See also