azure-static-web-apps

概要

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

主な機能:

• API プロキシと認証シミュレーションを備えたローカルエミュレーター
• フレームワークの自動検出と構成
• Azure への直接デプロイ
• データベース接続のサポート

設定ファイル:

• swa-cli.config.json - CLI 設定、swa init によって作成されます (手動で作成しないでください)
• staticwebapp.config.json - ランタイム設定 (ルート、認証、ヘッダー、API ランタイム) - 手動で作成できます

一般的な手順

インストール

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

確認: npx swa --version

クイックスタートワークフロー

重要: 設定ファイルを作成するには常に 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 にデプロイします

設定ファイル

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"
  }
}

コマンドラインリファレンス

swa login

デプロイのために Azure で認証します。

swa login                              # Interactive login
swa login --subscription-id <id>       # Specific subscription
swa login --clear-credentials          # Clear cached 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                    # Interactive setup
swa init --yes              # Accept defaults

swa build

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

swa build                   # Build using config
swa build --auto            # Auto-detect and build
swa build myApp             # Build specific configuration

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

swa start

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

swa start                                    # Serve from outputLocation
swa start ./dist                             # Serve specific folder
swa start http://localhost:3000              # Proxy to dev server
swa start ./dist --api-location ./api        # With API folder
swa start http://localhost:3000 --run "npm start"  # Auto-start dev server

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

フレームワーク	ポート
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                              # Deploy using config
swa deploy ./dist                       # Deploy specific folder
swa deploy --env production             # Deploy to production
swa deploy --deployment-token <TOKEN>   # Use deployment token
swa deploy --dry-run                    # Preview without deploying

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

• Azure Portal: Static Web App → 概要 → デプロイトークンの管理
• 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

シナリオ

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

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

# 1. Install CLI
npm install -D @azure/static-web-apps-cli

# 2. Initialize - REQUIRED: creates swa-cli.config.json with auto-detected settings
npx swa init              # Interactive mode
# OR
npx swa init --yes        # Accept auto-detected defaults

# 3. Build application (if needed)
npm run build

# 4. Test locally (uses settings from swa-cli.config.json)
npx swa start

# 5. Deploy
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. staticwebapp.config.json で API ランタイムを設定します:

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

4. swa-cli.config.json で CLI 設定を更新します:

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

5. ローカルでテストします:

npx swa start ./dist --api-location ./api
# Access API at 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. SWA リソースを作成 - Azure Portal または Azure CLI で
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 - カスタムビルドコマンド

トラブルシューティング

問題	解決策
クライアントルートで 404	staticwebapp.config.json に rewrite: "/index.html" を指定した navigationFallback を追加します
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        # Verbose output
swa deploy --dry-run           # Preview deployment
swa --print-config             # Show resolved configuration