SWA CLI で Config ファイルを使った実行がサポートされました

Posted on

Azure Static Web Apps CLI (以下 SWA CLI) は、SWA にホスティングする Web アプリケーションのローカル開発環境で、SWA の各種機能や振る舞いを再現できるエミュレーターです。GitHub 上で OSS として開発されており、プレビューがリリースされて以降日々活発に開発が続けられています。

先日リリースされた 0.8.0 でもいろいろなアップデートがありましたが、特に swa-cli.config.json ファイルのサポートが追加されました。

SWA CLI には多彩な実行オプションがあるのですが、オプションをたくさん指定して実行するとコマンドが長くなってしまいます。今回追加された config ファイルを使えば、それらオプションを全て設定ファイルに書いておけるので、コマンド自体が非常にシンプルになり開発体験が向上します。

SWA CLI のセットアップ

よく使う場合はローカルの Node.js 環境にグローバルでインストールします。

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

nvm や nodenv などの Node バージョン切り替えツールを使っている場合は、それぞれの Node.js 環境にインストールが必要です。最近 LTS になった Node.js 16.x 系でも特に問題なく動くようです。

グローバルでのインストールを避けたい場合は npx での実行も可能です。

npx @azure/static-web-apps-cli start

通常の CLI 実行方法

config ファイルを使わないで実行する場合は、swa コマンドに -- で各種オプションを付加していく感じになります。

出力された静的ファイルで実行する（出力先が dist のケース)

swa start ./dist

dev server を使って実行する（Vite のケース)

swa start http://localhost:3000 --run "npm run dev"

API (Managed Function) も同時に実行する

swa start http://localhost:3000 --run "npm run dev" --api-location http://localhost:7071

さらに --swa-config-location や --port , --ssl などのオプションを追加するともうコマンドで都度入力するには非現実的な長さと複雑さになっていきます。

swa-cli.config.json を使った CLI の実行

今回追加された swa-cli.config.json では、上記のようにコマンドにオプションで追加していた設定項目を以下のように json ファイルに定義をすることができるようになりました。

{
  "configurations": {
    "app": {
      "context": "http://localhost:3000",
      "apiLocation": "api",
      "run": "npm run dev",
      "swaConfigLocation": "./"
    }
  }
}

上記の config ファイルは、swa start http://localhost:3000 --run "npm run dev" --api-location ./api と同じ意味で、実行は以下のように設定ファイルで指定した configuration 名（例では app）を指定するだけと、非常にシンプルになります。

swa start app

config ファイル利用の利点として、複数の configuration を設定することができます。

{
  "$schema": "https://raw.githubusercontent.com/Azure/static-web-apps-cli/main/schema/swa-cli.config.schema.json",
  "configurations": {
    "dev": {
      "context": "http://localhost:3000",
      "run": "npm run dev",
      "apiLocation": "api"
    },
    "static": {
      "context": "./dist",
      "apiLocation": "api",
      "ssl": true,
      "sslCert": "/home/user/ssl/example.crt",
      "sslKey": "/home/user/ssl/example.key",
      ""
    }
  }
}

HMR を効かせて開発する場合には swa start dev とし、ビルド後に HTTPS 環境で動作確認するには swa start static などと使い分けができるようになります。なお、json の最初に $schema を登録しておくと、補完やチェックが効くようになるのでおすすめです。

また、config ファイルをプロジェクト共通の実行設定としてリポジトリに保存できるので、チーム内でのローカル実行環境の統一にも便利ではないでしょうか。