【SPFx】SharePoint Frameworkの開発環境構築手順

2026年1月7日

SharePoint Framework（SPFx）でWebパーツを開発するための環境構築手順をまとめました。

公式ドキュメントの日本語版は長らく更新されていないため、最新バージョン（v1.22.1）に対応した環境構築方法を解説します。

目次（クリックでジャンプできます）

前提環境

今回構築した環境は以下のとおりです。

macOS Sequoia 15.7.2
Visual Studio Code
SharePoint Framework v1.22.1
pnpm v10.7.1

なお、公式ドキュメントではnpmを使用していますが、私は好みでpnpmを選択しています。npmでも問題なく動作しますので、お好みで選択してください。

また、ターミナルのコマンドはmacOSのBashコマンドになっていますが、Windowsでも環境変数の設定以外は同じコマンドで問題なく進められるはずです。

SPFxのバージョンと参照するドキュメントに注意

Microsoft Learnは英語版を参照すること

日本語版のMicrosoft Learnの環境構築ページは長らく更新されていないため、執筆時点のSPFx最新バージョンであるv1.22.1に対応していません。

必ず英語版の公式ドキュメントを参照してください。

Microsoft Learn

Set up your SharePoint Framework development environment Learn how set up your development environment for the SharePoint Framework Heft-based toolchain.

v1.21.1以前とv.1.22以降で大幅な変更あり

v1.22からビルドツールがHeftに変更されました。

v.1.21.1以前のGulp用の構築手順と、一部異なる点があります。

本記事ではHeftベースの環境構築について解説しています。Gulpで環境を構築したい場合は、以下のLearnを参照してください。

Microsoft Learn

Set up your SharePoint Framework Gulp-Based development environment Learn how set up your development environment for the SharePoint Framework legacy gulp-based toolchain.

環境構築手順

0. Node.jsのインストール

Node.jsが導入されていない場合は、先にインストールしておきます。

Bash

node --version

そのままグローバルにインストールしても構いませんが、バージョン管理ツール（nvmやnvm-windows）を使ったほうが後々便利です。

1. 開発用ディレクトリを作成

まずはプロジェクト用のディレクトリを作成し、移動します。

Bash

mkdir spfx-tutorial1 && cd $_

2. 必要な依存関係をインストール

pnpmで必要な依存関係（Heft・Yeoman・Yeoman SharePoint generator）をグローバルにインストールします。

Bash

pnpm install @rushstack/heft yo @microsoft/generator-sharepoint --global

3. 開発用自己証明書を信頼する

ローカルの開発者環境でWebパーツをホスティングする場合は、heftに開発用の自己証明書を信頼させる必要があります。

以下をVSCodeのターミナルではなく、独立したターミナルで実行してください。

Bash

heft trust-dev-cert

VSCode下部のターミナルで実行しようとすると、実行途中で開かれた別ウィンドウのターミナルと連携が取れずに失敗するため注意してください。

4. Yeomanでプロジェクトを作成

yo @microsoft/sharepointコマンドでプロジェクトを作成します。

Yeomanが必要な各種ファイルの作成とnode_modulesのインストールを自動で行ってくれます。

pnpmを使用する場合は--package-manager引数でpnpmを指定します。npmを使う場合は省略して構いません。

Bash

yo @microsoft/sharepoint --package-manager pnpm

あとはウィザードに従って、求められた入力項目を埋めていきます。

5. 環境変数でテナントドメインを設定

heft start --cleanで参照される初期ページのURLはsrc/serve.jsonで指定されていますが、このinitialPageのURLのうち、{tenantDomain}の部分は環境変数SPFX_SERVE_TENANT_DOMAINから動的に読み込まれています。

JSON

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/spfx-serve.schema.json",
  "port": 4321,
  "https": true,
  "initialPage": "https://{tenantDomain}/_layouts/workbench.aspx"
}

環境変数が未設定だとそのまま{tenantDomain}がぶち込まれてアクセスできないので、環境変数を設定する必要があります。

macOSで環境変数を一時的にセットする

macOSで一時的に環境変数をセットする場合は、以下のようにします。

Bash

export SPFX_SERVE_TENANT_DOMAIN=example.sharepoint.com

echo $SPFX_SERVE_TENANT_DOMAIN # 正しく設定できたか確認

macOSで永続的に環境変数をセットするには

ターミナルでexportを打っただけだと、ターミナルを再起動すると設定が消えてしまいます。

永続的に環境変数を保存する場合は.zshrcに書き込みます。

まずは下のコマンドで.zshrcをvimで開きます。

Bash

vi ~/.zshrc

.zshrcの中身が表示されたら、「I」キーを押して編集モードに入ります。ターミナルの下部に-- INSERT --と表示されればOKです。

他の記述内容を壊さないように気をつけて、以下を追記します。

Bash

export SPFX_SERVE_TENANT_DOMAIN=example.sharepoint.com

追記したら「Esc」キーを押して編集モードを終了します。-- INSERT --表示が消えたことを確認したら、以下のコマンドを打って変更を保存します。

Bash

:wq

ターミナルを再起動して、echoコマンドで設定した値が正しく表示されていれば成功です。

Bash

echo $SPFX_SERVE_TENANT_DOMAIN

Windowsでの設定方法については、以下のページを参照してください。

Voitanos®

Setting the SharePoint Framework Hosted Workbench Test Site Why doesn’t the SharePoint hosted workbench load for new projects? You probably forgot to do this one small step when you setup your dev environment.

6. ブラウザで表示してみる

ここまでの手順で準備が整ったので、実際にブラウザで表示してみましょう。

Bash

pnpm run start

ブラウザでSharePointのWorkbenchが立ち上がります。

SharePointページの編集画面になっているので、新しいWebパーツの選択から今回作成した「HelloWorld」を探して、ページに追加します。

画面にWebパーツが表示されれば、環境構築とプロジェクトの作成は無事終了です。

Webパーツの実装場所

ちなみに表示されているWebパーツの内容はsrc/webparts/helloWorld/HelloWorldWebPart.tsに実装されています。

主要な部分を抜粋すると、以下のような構造になっています。

TypeScript

export default class HelloWorldWebPart extends BaseClientSideWebPart<IHelloWorldWebPartProps> {

  public render(): void {
    this.domElement.innerHTML = `
    <section class="${styles.helloWorld}">
      <div class="${styles.welcome}">
        <h2>Well done, ${escape(this.context.pageContext.user.displayName)}!</h2>
        <div>${this._environmentMessage}</div>
        <div>Web part property value: <strong>${escape(this.properties.description)}</strong></div>
      </div>
      <div>
        <h3>Welcome to SharePoint Framework!</h3>
        <p>
        The SharePoint Framework (SPFx) is a extensibility model for Microsoft Viva, Microsoft Teams and SharePoint.
        </p>
      </div>
    </section>`;
  }

  // 省略
}