azure-static-web-apps

Overview

Azure Static Web Apps (SWA) は、静的フロントエンドとオプションのサーバーレス API バックエンドをホストします。SWA CLI (swa) はローカル開発エミュレーション機能とデプロイ機能を提供します。

主な機能:

• API プロキシと認証シミュレーション付きローカルエミュレータ
• フレームワーク自動検出と設定
• Azure への直接デプロイメント
• データベース接続サポート

設定ファイル:

• swa-cli.config.json - CLI 設定、swa init によって作成 (手動で作成しないこと)
• staticwebapp.config.json - ランタイム設定 (ルート、認証、ヘッダー、API ランタイム) - 手動で作成可能

General Instructions

Installation

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

確認: npx swa --version

Quick Start Workflow

重要: 設定ファイルを作成する際は常に swa init を使用してください。swa-cli.config.json を手動で作成しないでください。

1. swa init - 必須の最初のステップ - フレームワークを自動検出して swa-cli.config.json を作成
2. swa start - ローカルエミュレータを http://localhost:4280 で実行
3. swa login - Azure で認証
4. swa deploy - Azure にデプロイ

Configuration Files

swa-cli.config.json - swa init によって作成され、手動では作成しない:

• swa init で対話的セットアップとフレームワーク検出を実行
• swa init --yes で自動検出のデフォルトを受け入れる
• 初期化後に設定をカスタマイズする場合のみ生成されたファイルを編集

生成される設定例 (参考用):

{
  "$schema": "https://aka.ms/azure/static-web-apps-cli/schema",
  "configurations": {
    "app": {
      "appLocation": ".",
      "apiLocation": "api",
      "outputLocation": "dist",
      "appBuildCommand": "npm run build",
      "run": "npm run dev",
      "appDevserverUrl": "http://localhost:3000"
    }
  }
}

staticwebapp.config.json (アプリソースまたは出力フォルダ内) - このファイルはランタイム設定のために手動で作成できます:

{
  "navigationFallback": {
    "rewrite": "/index.html",
    "exclude": ["/images/*", "/css/*"]
  },
  "routes": [
    { "route": "/api/*", "allowedRoles": ["authenticated"] }
  ],
  "platform": {
    "apiRuntime": "node:20"
  }
}

Command-line Reference

swa login

デプロイメント用に Azure で認証します。

swa login                              # 対話的ログイン
swa login --subscription-id <id>       # 特定のサブスクリプション
swa login --clear-credentials          # キャッシュされた認証情報をクリア

フラグ: --subscription-id, -S | --resource-group, -R | --tenant-id, -T | --client-id, -C | --client-secret, -CS | --app-name, -n

swa init

既存フロントエンドと (オプション) API に基づいて新しい SWA プロジェクトを設定します。フレームワークを自動検出します。

swa init                    # 対話的セットアップ
swa init --yes              # デフォルトを受け入れ

swa build

フロントエンドまたは API をビルドします。

swa build                   # 設定を使用してビルド
swa build --auto            # 自動検出してビルド
swa build myApp             # 特定の設定をビルド

フラグ: --app-location, -a | --api-location, -i | --output-location, -O | --app-build-command, -A | --api-build-command, -I

swa start

ローカル開発エミュレータを起動します。

swa start                                    # outputLocation から提供
swa start ./dist                             # 特定フォルダを提供
swa start http://localhost:3000              # 開発サーバーへプロキシ
swa start ./dist --api-location ./api        # API フォルダ付き
swa start http://localhost:3000 --run "npm start"  # 開発サーバーを自動起動

一般的なフレームワークポート:

フレームワーク	ポート
React/Vue/Next.js	3000
Angular	4200
Vite	5173

主要フラグ:

• --port, -p - エミュレータポート (デフォルト: 4280)
• --api-location, -i - API フォルダパス
• --api-port, -j - API ポート (デフォルト: 7071)
• --run, -r - 開発サーバーを起動するコマンド
• --open, -o - ブラウザを自動で開く
• --ssl, -s - HTTPS を有効化

swa deploy

Azure Static Web Apps にデプロイします。

swa deploy                              # 設定を使用してデプロイ
swa deploy ./dist                       # 特定フォルダをデプロイ
swa deploy --env production             # 本番環境にデプロイ
swa deploy --deployment-token <TOKEN>   # デプロイメントトークンを使用
swa deploy --dry-run                    # デプロイせずにプレビュー

デプロイメントトークンの取得:

• Azure Portal: Static Web App → Overview → Manage deployment token
• CLI: swa deploy --print-token
• 環境変数: SWA_CLI_DEPLOYMENT_TOKEN

主要フラグ:

• --env - ターゲット環境 (preview または production)
• --deployment-token, -d - デプロイメントトークン
• --app-name, -n - Azure SWA リソース名

swa db

データベース接続を初期化します。

swa db init --database-type mssql
swa db init --database-type postgresql
swa db init --database-type cosmosdb_nosql

Scenarios

既存フロントエンドとバックエンドから SWA を作成

swa start または swa deploy の前に必ず swa init を実行してください。swa-cli.config.json を手動で作成しないでください。

# 1. CLI をインストール
npm install -D @azure/static-web-apps-cli

# 2. 初期化 - 必須: 自動検出された設定で swa-cli.config.json を作成
npx swa init              # 対話型モード
# または
npx swa init --yes        # 自動検出されたデフォルトを受け入れ

# 3. アプリケーションをビルド (必要な場合)
npm run build

# 4. ローカルでテスト (swa-cli.config.json の設定を使用)
npx swa start

# 5. デプロイ
npx swa login
npx swa deploy --env production

Azure Functions バックエンドを追加

1. API フォルダを作成:

mkdir api && cd api
func init --worker-runtime node --model V4
func new --name message --template "HTTP trigger"

2. 例関数 (api/src/functions/message.js):

const { app } = require('@azure/functions');

app.http('message', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    handler: async (request) => {
        const name = request.query.get('name') || 'World';
        return { jsonBody: { message: `Hello, ${name}!` } };
    }
});

3. API ランタイムを設定 (staticwebapp.config.json 内):

{
  "platform": { "apiRuntime": "node:20" }
}

4. CLI 設定を更新 (swa-cli.config.json 内):

{
  "configurations": {
    "app": { "apiLocation": "api" }
  }
}

5. ローカルでテスト:

npx swa start ./dist --api-location ./api
# API に http://localhost:4280/api/message でアクセス

サポートされる API ランタイム: node:18, node:20, node:22, dotnet:8.0, dotnet-isolated:8.0, python:3.10, python:3.11

GitHub Actions デプロイメントをセットアップ

1. Azure Portal または Azure CLI で SWA リソースを作成
2. GitHub リポジトリをリンク - ワークフロー自動生成、または手動で作成:

.github/workflows/azure-static-web-apps.yml:

name: Azure Static Web Apps CI/CD

on:
  push:
    branches: [main]
  pull_request:
    types: [opened, synchronize, reopened, closed]
    branches: [main]

jobs:
  build_and_deploy:
    if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.action != 'closed')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Build And Deploy
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
          repo_token: ${{ secrets.GITHUB_TOKEN }}
          action: upload
          app_location: /
          api_location: api
          output_location: dist

  close_pr:
    if: github.event_name == 'pull_request' && github.event.action == 'closed'
    runs-on: ubuntu-latest
    steps:
      - uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
          action: close

3. シークレットを追加: デプロイメントトークンをリポジトリシークレット AZURE_STATIC_WEB_APPS_API_TOKEN にコピー

ワークフロー設定:

• app_location - フロントエンドソースパス
• api_location - API ソースパス
• output_location - ビルド出力フォルダ
• skip_app_build: true - プリビルド済みの場合スキップ
• app_build_command - カスタムビルドコマンド

Troubleshooting

問題	解決方法
クライアントルートで 404	staticwebapp.config.json に navigationFallback と rewrite: "/index.html" を追加
API が 404 を返す	api フォルダ構造を確認、platform.apiRuntime が設定されていることを確認、関数エクスポートをチェック
ビルド出力が見つからない	output_location が実際のビルド出力ディレクトリと一致することを確認
ローカルで認証が機能しない	/.auth/login/<provider> で認証エミュレータ UI にアクセス
CORS エラー	/api/* 下の API は同一オリジン。外部 API は CORS ヘッダーが必要
デプロイメントトークン期限切れ	Azure Portal → Static Web App → Manage deployment token で再生成
設定が適用されない	staticwebapp.config.json が app_location または output_location にあることを確認
ローカル API タイムアウト	デフォルト 45 秒。関数を最適化するか、ブロッキング呼び出しをチェック

デバッグコマンド:

swa start --verbose log        # 詳細出力
swa deploy --dry-run           # デプロイメントプレビュー
swa --print-config             # 解決された設定を表示