SharePoint Framework ツールチェーンにおける Gulp タスクの統合Integrate gulp tasks in SharePoint Framework toolchain

SharePoint のクライアント側の開発ツールは、gulp をビルド プロセスのタスク ランナーとして使用し次のことを行います。SharePoint client-side development tools use gulp as the build process task runner to:

  • JavaScript と CSS ファイルをバンドルし、縮小します。Bundle and minify JavaScript and CSS files.
  • ツールを実行して、各ビルドの前にバンドル化タスクと縮小タスクを呼び出します。Run tools to call the bundling and minification tasks before each build.
  • LESS または Sass ファイルを CSS にコンパイルします。Compile LESS or Sass files to CSS.
  • TypeScript ファイルを JavaScript にコンパイルします。Compile TypeScript files to JavaScript.

SharePoint Framework ツールチェーンに追加する一般的なタスクの 1 つとして、ビルド パイプラインにカスタム Gulp タスクを統合するというタスクがあります。One common task you can add to the SharePoint Framework toolchain is to integrate your custom gulp tasks in the build pipeline.

Gulp タスクGulp tasks

Gulp タスクは、通常、gulpfile.js で次のように定義されます。Normally gulp tasks are defined in the gulpfile.js as:

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


SharePoint Framework ツールチェーンを扱う場合は、フレームワークのビルド パイプラインにタスクを定義する必要があります。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 は共通のビルド ツールチェーンを使用します。これは、共通のビルド タスクを共有する NPM パッケージのセットで構成されます。SharePoint Framework uses a common build toolchain that consists of a set of npm packages that share common build tasks. そのため、クライアント側のプロジェクトの gulpfile.js とは対照的に、既定のタスクは共有パッケージに定義されます。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.

利用可能な Gulp タスク

カスタムの Gulp タスクCustom gulp tasks

カスタム タスクを追加するには、gulpfile.js でカスタム タスクを定義します。To add your custom tasks, define the custom tasks in the gulpfile.js.

コード エディターで gulpfile.js を開きます。Open the gulpfile.js in your code editor. 既定のコードによって SharePoint Framework ツールチェーンと、ツールチェーンのグローバル gulp インスタンスが初期化されます。The default code initializes the SharePoint Framework toolchain and the global gulp instance for the toolchain. 追加するすべてのカスタム タスクは、グローバル gulp インスタンスの初期化前に定義しておく必要があります。Any custom tasks added should be defined before initializing the global gulp instance.

カスタム タスクの追加Add your custom task

カスタムの Gulp タスクを追加するには、build.subTask 関数を使用して SharePoint Framework ビルド パイプラインに新しいサブタスクを追加します。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')
             .pipe(gulp.dest('public'));
});

Gulp コマンドラインでのタスクの登録Register your task with gulp command line

カスタム タスクの定義後、そのカスタム タスクは build.task 関数を使用して Gulp コマンドラインで登録できます。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);

注意

追加するすべてのカスタム タスクは、グローバル gulp インスタンスの初期化前 (build.initialize(gulp); というコード行より前) に定義しておく必要があります。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

注意

コマンドラインから build.subTask 関数を使用して、登録したサブタスクを直接実行することはできません。You cannot execute the subtask registered by using the build.subTask function directly from the command line. 登録したタスクは build.task 関数を使用してのみ実行できます。You can only execute the task registered by using the build.task function.

利用可能なタスクの前後におけるカスタム タスクの実行Execute your custom task before or after available tasks

このカスタム タスクを、利用可能な特定の Gulp タスクの前または後に実行するように追加することもできます。You can also add this custom task to be executed before or after certain available gulp tasks. 次に示す Gulp タスクでは、そのタスクの前または後にカスタム タスクを挿入できます。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 タスクTypeScript task

SharePoint Framework タスクは既定の build rig で利用できます。The SharePoint Framework tasks are available in the default build rig. build rig は、特定の目的のために定義されたタスク コレクションです。ここでは、クライアント側パッケージのビルドを目的としています。The build rig is a collection of tasks defined for a specific purpose, in our case, building client-side packages. build.rig オブジェクトを使用すると、この既定の rig にアクセスして、タスク前後の関数にアクセスできます。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
build.rig.addPreBuildTask(helloWorldTask);

// execute after TypeScript subtask
build.rig.addPostTypescriptTask(helloWorldTask);

// execute after all tasks
build.rig.addPostBuildTask(helloWorldTask);

例:カスタムのイメージ サイズ変更タスクExample: Custom image resize task

例として、イメージ サイズ変更 Gulp タスク を使用してみましょう。これは、イメージのサイズを変更できるようにする簡単なタスクです。As an example, let's use the image resize gulp task. It's a simple task that allows you to resize images.

完成したサンプルは、samples/js-extend-gulp/ からダウンロードできます。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 () {
  gulp.src('test.png')
    .pipe(imageResize({
      width : 100,
      height : 100,
      crop : true,
      upscale : false
    }))
    .pipe(gulp.dest('dist'));
});


この情報は、build.subTask 関数と build.task 関数を使用して、このプロジェクトに対象タスクを追加するために使用しています。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')
               .pipe(imageResize({
                   width: 100,
                   height: 100,
                   crop: false                   
               }))
               .pipe(gulp.dest(path.join(buildOptions.libFolder, 'images')))
});

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


ここではストリームを定義しているため、build.subTask 関数でビルド パイプラインにストリームを返しています。その後、ビルド パイプラインは、この Gulp ストリームを非同期的に実行します。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.

これで、Gulp コマンドラインからこのタスクを次のように実行できるようになりました。Now, you can execute this task from the gulp command line as follows:

gulp resize-images


イメージ サイズ変更タスク


gulp --tasks を実行すると、プロジェクトで利用可能なタスクに、この resize-images タスクも表示されます。You also see this resize-images task in the available tasks for your project when you execute gulp --tasks:

イメージ サイズ変更タスクと利用可能なタスク

関連項目See also