Azure Static Web Apps 用にローカル開発環境を設定する

  • [アーティクル]

Azure Static Web Apps サイトでは、クラウドに発行されると、同じアプリケーションであるかのように連携して動作する多くのサービスがリンクされます。 これらのサービスには、次のようなものがあります。

  • 静的 Web アプリ
  • Azure Functions API
  • 認証と承認のサービス
  • ルーティングと構成のサービス

これらのサービスは相互に通信する必要があり、Azure Static Web Apps によってクラウドでこの統合が処理されます。

ただし、アプリケーションをローカルで実行する場合、これらのサービスは自動的に関連付けられません。

Azure で使用した場合と同様のエクスペリエンスを提供するために、Azure Static Web Apps CLI には次のサービスが用意されています。

  • ローカルの静的サイト サーバー
  • フロントエンド フレームワーク開発サーバーへのプロキシ
  • API エンドポイントへのプロキシ (Azure Functions Core Tools を通じて利用可能)
  • モックの認証と承認サーバー
  • ローカル ルートと構成設定の適用

Note

多くの場合、フロントエンド フレームワークを使用して構築されたサイトでは、api ルートで要求を正しく処理するためにプロキシ構成設定が必要です。 Azure Static Web Apps CLI を使用する場合、プロキシの場所の値は /api になり、CLI を使用しない場合、この値は http://localhost:7071/api になります。

動作方法

次のグラフは、要求がローカルで処理される方法を示しています。

Diagram showing the Azure Static Web App CLI request and response flow.

重要

CLI によって処理されるアプリケーションにアクセスするには、http://localhost:4280 に移動します。

  • ポート 4280 に対して行われた要求は、要求の種類に応じて適切なサーバーに転送されます。

  • HTML や CSS などの静的コンテンツ要求は、内部 CLI 静的コンテンツ サーバーによって、またはデバッグ用のフロントエンド フレームワーク サーバーによって処理されます。

  • 認証と承認要求は、アプリにフェイク ID プロファイルを提供するエミュレーターによって処理されます。

  • Functions Core Tools ランタイム1 では、サイトの API への要求が処理されます。

  • すべてのサービスからの応答は、すべて 1 つのアプリケーションであるかのようにブラウザーに返されます。

UI と Azure Functions API アプリを別個に起動したら、Static Web Apps CLI を起動し、次のコマンドを使用して実行中のアプリを指定してください。

swa start http://localhost:<DEV-SERVER-PORT-NUMBER> --api-location http://localhost:7071

必要に応じて、swa init コマンドを使用する場合、Static Web Apps CLI は、アプリケーション コードを確認し、CLI 用の swa-cli.config.json 構成ファイルをビルドします。 swa-cli.config.json ファイルを使用すると、swa start を実行して、アプリケーションをローカルで起動することができます。

1 Azure Functions Core Tools は、お使いのシステムにまだインストールされていない場合、CLI によって自動的にインストールされます。

次の記事では、ノードベースのアプリケーションを実行する手順について詳しく説明しますが、このプロセスはどの言語または環境でも同じです。

前提条件

  • 既存の Azure Static Web Apps サイト: お持ちでない場合は、vanilla-api スターター アプリから開始してください。
  • npm を含む Node.js: npm へのアクセスを含む Node.js LTS バージョンを実行します。
  • Visual Studio Code: API アプリケーションのデバッグに使用されますが、CLI には必要ありません。

はじめに

ターミナルで、既存の Azure Static Web Apps サイトのルート フォルダーを開きます。

  1. CLI をインストールします。

    npm install -D @azure/static-web-apps-cli

    ヒント

    SWA CLI をグローバルにインストールする場合は、次の-D代わりに使用-gします。 ただし、開発の依存関係として SWA をインストールすることを強くお勧めします。

  2. アプリケーションで必要な場合は、アプリをビルドします。

    npm run build、またはプロジェクトに対応する同等のコマンドを実行します。

  3. CLI のリポジトリを初期化します。

    swa init

    CLI によって示される質問に回答して、構成設定が正しいことを確認します。

  4. CLI を起動します。

    swa start

  5. ブラウザーでアプリを表示するには、http://localhost:4280 に移動します。

CLI を起動するその他の方法

説明 コマンド 説明
特定のフォルダーを処理する swa start ./<OUTPUT_FOLDER_NAME> <OUTPUT_FOLDER_NAME> は、実際の出力フォルダーの名前に置き換えます。
実行中のフレームワーク開発サーバーを使用する swa start http://localhost:3000 このコマンドは、アプリケーションのインスタンスがポート 3000 で実行されている場合に機能します。 構成が異なる場合は、ポート番号を更新します。
フォルダー内の Functions アプリを起動する swa start ./<OUTPUT_FOLDER_NAME> --api-location ./api <OUTPUT_FOLDER_NAME> は、実際の出力フォルダーの名前に置き換えます。 このコマンドは、アプリケーションの API がフォルダー内にファイルを api 含む必要があります。 構成が異なる場合は、この値を更新します。
実行中の Functions アプリを使用する swa start ./<OUTPUT_FOLDER_NAME> --api-location http://localhost:7071 <OUTPUT_FOLDER_NAME> は、実際の出力フォルダーの名前に置き換えます。 このコマンドは、Azure Functions アプリケーションがポート 7071 を介して使用できることを想定しています。 構成が異なる場合は、ポート番号を更新します。

承認と認証のエミュレーション

Azure Static Web Apps CLI は、Azure で実装されているセキュリティ フローをエミュレートします。 ユーザーがログインするときに、アプリに返されるフェイク ID プロファイルを定義できます。

たとえば、/.auth/login/github に移動しようとすると、ID プロファイルを定義できるページが返されます。

Note

エミュレーターは、GitHub だけでなく、あらゆるセキュリティ プロバイダーで動作します。

Local authentication and authorization emulator

エミュレーターによって、次のクライアント プリンシパルの値を指定できるページが提供されます。

値 説明
ユーザー名 セキュリティ プロバイダーに関連付けられているアカウント名。 この値は、クライアント プリンシパルの userDetails プロパティとして表示され、値を指定しない場合に自動生成されます。
[ユーザー ID] CLI によって自動生成される値。
ロール ロール名のリスト。各名前は新しい行に表示されます。
請求 ユーザー クレームのリスト。各名前は新しい行に表示されます。

ログインすると、次のようになります。

  • /.auth/me エンドポイント、または関数エンドポイントを使用して、ユーザーのクライアント プリンシパルを取得できます。

  • 移動して /.auth/logout クライアント プリンシパルをクリアし、モック ユーザーをサインアウトします。

デバッグ

静的 Web アプリには、2 つのデバッグ コンテキストがあります。 1 つ目は静的コンテンツ サイト用で、2 つ目は API 関数用です。 Static Web Apps CLI でこれらのコンテキストのいずれかまたは両方に開発サーバーを使用できるようにすることで、ローカル デバッグを実行できます。

次の手順では、両方のデバッグ コンテキストで開発サーバーを使用する一般的なシナリオを示します。

  1. 静的サイト開発サーバーを起動します。 このコマンドは、使用しているフロントエンド フレームワークに固有のものですが、多くの場合、npm run build、npm start、または npm run dev のようなコマンドの形式になります。

  2. Visual Studio Code で API アプリケーション フォルダーを開き、デバッグ セッションを開始します。

  3. 次のコマンドで Static Web Apps CLI を起動します。

    swa start http://localhost:<DEV-SERVER-PORT-NUMBER> --appDevserverUrl http://localhost:7071

    開発サーバーのポート番号で <DEV_SERVER_PORT_NUMBER> を置き換えてください。

次のスクリーンショットは、一般的なデバッグ シナリオでのターミナルを示しています。

静的コンテンツ サイトは、npm run dev を使用して実行されています。

Static site development server

Azure Functions API アプリケーションにより、Visual Studio Code でデバッグ セッションが実行されています。

Visual Studio Code API debugging

Static Web Apps CLI が両方の開発サーバーを使用して起動されます。

Azure Static Web Apps CLI terminal

ポート 4280 を経由する要求は、静的コンテンツ開発サーバー、または API デバッグ セッションのいずれかにルーティングされるようになりました。

ポートとサーバー アドレスをカスタマイズする方法のガイダンスを含む、さまざまなデバッグ シナリオの詳細については、Azure Static Web Apps CLI リポジトリに関するページを参照してください。

デバッグ構成の例

Visual Studio Code では、ファイルを使用してエディターのデバッグ セッションを有効にします。 Visual Studio Code で launch.json が生成されない場合は、.vscode/launch.json に次の構成を配置できます。

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Attach to Node Functions",
            "type": "node",
            "request": "attach",
            "port": 9229,
            "preLaunchTask": "func: host start"
        }
    ]
}

次のステップ

アプリケーションの構成