Azure Static Web Appsのデプロイ設定の理解と、そのカスタマイズ方法について
はじめに
TL;DR
GitHub Actions の設定ファイル（.yml ファイル）を編集することで、
ビルドコマンドを変更したり別のステップでビルドしたりといった、デプロイ構成のカスタマイズができます。
本記事の概要
Azure Static Web Apps（以下 Azure SWA）は静的な Web ページをホスティングできる Azure サービスです。
GitHub リポジトリと連携すると自動でデプロイの設定がされるため、手軽に Web ページを公開できる便利なサービスになっています。
Azure SWA のデプロイには GitHub Actions が使われますが、設定ファイルを自動で追加してくれるので開発者が直接 .yaml ファイルを手書きする必要はありません。
そのため、具体的にどんなデプロイ構成になっているかを意識することは少ないでしょう。
本記事では、もし Azure SWA でデプロイ構成をカスタマイズしたくなったときに
どのように設定していけばよいのかを解説します。
実は本記事で説明する事項はすべて次の公式ドキュメントにまとまっているので、そちらも合わせてご参照ください。
また、本記事ではフロントエンドアプリについてのみ解説するため、API 部分の説明は省いております。
対象読者
- Azure SWA のデプロイスクリプトをカスタマイズしたい方
- Web フロントエンド開発経験がある方
- Azure SWA を知っている方
- GitHub Actions を使ったことがある方
想定環境
特にサンプルなどを用意しているわけではありませんが、
本記事ではNode.js によってビルドする Web フロントエンド開発環境を想定して書いております。
例えば React や Vue といったフレームワークを導入していたり、 Vite や Webpack でビルドしたりするタイプの環境が該当します。
Azure SWA では Blazor などの環境にも対応していますが、もしそちらをご利用される際には適宜内容を読み替えていただきたいです。
デプロイ構成のカスタマイズ
デフォルトの構成
例えば create-vite を使って Vue ＋ TypeScript なプロジェクトを作ると次のようなpackage.jsonが生成されます。
{
"name": "test-vite-vue",
"private": true,
"version": "0.0.0",
"type": "module",
"scripts": {
"dev": "vite",
"build": "vue-tsc --noEmit && vite build",
"preview": "vite preview"
},
"dependencies": {
"vue": "^3.2.37"
},
"devDependencies": {
"@vitejs/plugin-vue": "^3.1.0",
"typescript": "^4.6.4",
"vite": "^3.1.0",
"vue-tsc": "^0.40.4"
}
}
そして例えばyarn buildといったコマンドをたたくと、/dist以下にビルド成果物が生成されます。
このような構成の場合、Azure SWA リソースを作成する際には次のように設定項目を入力することになります。
この設定でリソースを作成すると、.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_job:
if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.action != 'closed')
runs-on: ubuntu-latest
name: Build and Deploy Job
steps:
- uses: actions/checkout@v2
with:
submodules: true
- name: Build And Deploy
id: builddeploy
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 }} # Used for Github integrations (i.e. PR comments)
action: "upload"
###### Repository/Build Configurations - These values can be configured to match your app requirements. ######
# For more information regarding Static Web App workflow configurations, please visit: https://aka.ms/swaworkflowconfig
app_location: "/" # App source code path
api_location: "" # Api source code path - optional
output_location: "dist" # Built app content directory - optional
###### End of Repository/Build Configurations ######
# 以下割愛
.yml ファイルの中では Node.js のセットアップはしていませんし、ビルドスクリプトの指定もされていませんが、ログを見るとちゃんとyarn run buildと実行されているようでした。どういうことでしょう。
Azure SWA のアクションでは最初にプラットフォームを判別し、Node.js や.NET といったランタイムのインストールを行います。
その後 Node.js だった場合、デフォルトで 「buildまたはbuild:azureを実行する」 と決められており、今回の場合はpackage.jsonでbuildが定義されているため実行されました。
ちなみにbuild:azureも一緒に定義されていると、どちらも実行されるみたいです。自分の環境ではbuild→build:azureという順番でした。
てっきりbuild:azureだけ実行されるのかなぁと思っていたのでこれは意外でしたね。
カスタマイズする
ビルドスクリプトをカスタマイズする
デフォルトの設定だとyarn run buildもしくはyarn run build:azureが実行されるのは前述のとおりですが、別のコマンドを実行したいケースもあるでしょう。
例えば Next.js や Nuxt.js といったフレームワークで SSG を行う際にはyarn run generateコマンドを実行するのが慣習です。
Azure SWA の actions では、app_build_commandによって実行コマンドを指定できます。
- name: Build And Deploy
id: builddeploy
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 }} # Used for Github integrations (i.e. PR comments)
action: "upload"
###### Repository/Build Configurations - These values can be configured to match your app requirements. ######
# For more information regarding Static Web App workflow configurations, please visit: https://aka.ms/swaworkflowconfig
app_location: "/" # App source code path
api_location: "" # Api source code path - optional
output_location: "dist" # Built app content directory - optional
+ app_build_command: "yarn generate" # generateコマンドを実行
###### End of Repository/Build Configurations ######
別の Step でビルドする
フロントエンドアプリのビルドを他のステップで実行したい場合もあるのではないでしょうか。
例えば自分の場合、 Nuxt.js の環境を docker-compose で構築していたので、
Docker コンテナ内でジェネレートをしたいケースがありました。
そういう場合はskip_app_buildオプションを true にすることで対応できます。
例えばAzure/static-web-apps-deployを実行する前に docker-compose で静的ジェネレートを行ったうえでデプロイするような yml は次のようになります（一部抜粋）。
- name: Build with docker-compose
run: |
docker-compose up -d
docker-compose exec -T app yarn install
docker-compose exec -T app yarn generate
- name: Build And Deploy
id: builddeploy
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 }} # Used for Github integrations (i.e. PR comments)
action: "upload"
###### Repository/Build Configurations - These values can be configured to match your app requirements. ######
# For more information regarding Static Web App workflow configurations, please visit: https://aka.ms/swaworkflowconfig
skip_app_build: true
app_location: "/src/.output/public" # App source code path
api_location: "" # Api source code path - optional
output_location: "" # Built app content directory - optional
###### End of Repository/Build Configurations ######
ここでポイントは次の通りです。
-
skip_app_buildが true になっている -
app_locationがビルド成果物のディレクトリになっている -
output_locationが空文字になっている
おわりに
今回は Azure SWA の少し凝った使い方を紹介しました。
調べているうちに自分でも初めて知ったことがいくつかあり、勉強になって良かったです。
最後まで読んでいただきありがとうございました。
参考文献
Discussion