道具立て — gulpからHeftへ

SPFxは「バージョンの噛み合わせ」で動いている

SPFxは単体で動いているのではなく、たくさんの部品（ライブラリ）を組み合わせて動いています。主な登場人物はこの4つです。

• Node.js — JavaScript/TypeScriptを動かす土台。ビルド作業のエンジン
• SPFx本体（@microsoft/generator-sharepoint など） — SharePoint向けの部品を作るための道具一式
• TypeScript — 実際にコードを書く言語
• React — 画面を組み立てるライブラリ

やっかいなのは、この4つが「決められた組み合わせ」でしか正しく動かないことです。たとえるなら、精密機械の歯車。1つでもサイズの違う歯車を入れると、全体が噛み合わずに止まってしまう。SPFxのバージョンごとに「この歯車にはこのNode.js」という対応が決まっているのです。

なぜ新しすぎるとダメなのか

Node.jsは年に数回、新しいバージョンが出ます。でもSPFxは、「動作確認が取れた特定のNode.js」でしか公式サポートされません。しかもサポート対象は、Node.jsの中でも安定版である LTS（Long Term Support） に限られます。

たとえば、この講座で対象とする SPFx 1.23 系 に対応するNode.jsは v22（LTS。コードネーム "Jod"）です。ここに最新の v24 などを入れてしまうと、ビルド時に予期せぬエラーが出る可能性がある——これが「新しすぎるとダメ」の正体です。

v1.22の大きな転換：gulp から Heft へ

もう1つ、知っておくべき歴史があります。SPFxの「ビルドの道具（ツールチェーン）」は、途中で大きく作り替えられました。

世代	SPFxバージョン	ビルドの道具	代表的なコマンド
従来（レガシー）	v1.0 〜 v1.21.1	gulp	gulp serve / gulp bundle
現行（モダン）	v1.22 以降	Heft	heft start / heft package-solution

ネット上のSPFx解説記事は、まだ古い gulp 前提のものが大量に残っています。この講座が対象とする 1.23 は Heft 世代。もし「gulp serve を実行」と書かれた記事を見つけても、それは一世代前の手順だと見抜けるようになってください。この講座は、すべて Heft 世代の手順で書いていきます。

だから、最初にやるのは「調べる」こと

ここまでをまとめると、SPFxの環境構築は次の順番になります。

1. 対象のSPFxバージョンを決める / 調べる（既存プロジェクトなら、そのバージョンに合わせる）
2. そのバージョンに対応するNode.jsのバージョンを調べる
3. 一致するNode.jsを入れ、ツールを入れる

いきなりインストールを始めないこと。まず「何を入れるべきか」を調べる——次の記事で、その具体的な調べ方をやっていきます。