himanago

Azure・C#などのMS系技術やLINE関連技術など、好きな技術について書くブログ

Next.js + Azure Static Web Apps + Azure Functions + Cosmos DB で効率よくアプリケーションを開発・ホストできるツールキット「SwallowKit」をリリースしました

Microsoft Azure Azure Static Web Apps Azure Functions Azure Cosmos DB SwallowKit TypeScript

昨今、アプリケーション開発そのものは AI の進歩により誰でも簡単にできるようになってきました。

アプリケーション開発が簡単にできても、その次のステップとして、アプリケーションを運用するためのインフラストラクチャを構築することが重要になってきています。

そこで今回、

  • 開発者フレンドリーな PaaS / サーバーレスで
  • ベストプラクティスに沿った構成で

アプリ開発の土台からインフラまで一挙に作成・管理できるツールが有用と考え、Azure Static Web Apps + Azure Functions + Cosmos DB で Next.js を効率よく開発・ホストできるツールキット「SwallowKit」を開発しました。

github.com

npm に公開しているので、npx からすぐに利用できます。

https://www.npmjs.com/package/swallowkit

SwallowKit とは

SwallowKit は、Azure 環境に最適化されたスキーマ駆動開発ツールキットです。

Next.js アプリを Azure Static Web Apps にスタンドアロンモードでデプロイし、独立した Azure Functions バックエンドと接続します。

SwallowKit の特徴

アプリの全スタックをコードファーストで構築できるコマンドラインツール

swallowkit コマンドを使用して、アプリの全スタックをコードファーストで構築できます。

コマンド 説明
npx swallowkit init <app-name> 新しいプロジェクトを初期化します。最新の Next.js を使用してアプリを作成し、SwallowKit 専用の構成・設定を適用します。
npx swallowkit create-model <model-name> データモデルを作成します。
npx swallowkit scaffold <model-name> モデルから CRUD コードを自動生成します。フロントエンドの画面に加え、BFF レイヤーと、Azure Functions バックエンドのコードを生成します。
npx swallowkit dev ローカル開発サーバー（Next.js + Azure Functions）を起動します。Cosmos DB Emulator を使用してローカルでの開発・デバッグが可能です。
npx swallowkit provision -g <resource-group-name> init 時に選択された構成をもとに生成された Bicep コードを使用し、Azureにリソースをプロビジョニングします。

Zod スキーマの共有と Next.js API を BFF としてのみ利用する構成

最大の特徴は、Zod スキーマを共有することで、フロントエンドからデータベースまで一貫した型安全性を保証できる点です。

Next.js API ルートは BFF (Backend For Frontend) として制限され、ビジネスロジックは Azure Functions にオフロードされるため、クライアントとサーバーの明確な分離が実現されます。

昨年から、React Server Components (RSC) / Next.js の脆弱性について大きな話題となることが増えてきていますが、SwallowKit では Next.js API ルートを BFF として制限することで、このセキュリティリスクを最小限に抑えています。

さらに、この構成をとることでバックエンドのビジネスロジック部分を Azure Functions で記述できるようになり 1 、強力な入出力バインディングや各種トリガーなどをフル活用することができます。

Microsoft Foundry などの AI モデルをはじめ、Azure のさまざまなサービスとの連携させて機能を拡張していくことが可能です。

Bicep（IaC）＆ GitHub Actions または Azure Pipelines（CI/CD）による簡単デプロイ

自動生成される Bicep IaC と CI/CD ワークフローにより、Azure へのデプロイが簡単に行えます。

Static Web Apps + Functions + Cosmos DB による最小コストかつセキュリティも考慮したアーキテクチャ構成で、インフラを意識せずアプリ開発に注力することを目指しています。

Azure リソースの構成

SwallowKit でプロビジョニングされる Azure リソースは以下のようなイメージです。

使用イメージ

0. 下準備

Azure CLI と Azure Functions Core Tools をインストールしておきます。

Azure CLI をインストールする方法 | Microsoft Learn

Core Tools を使用してローカルで Azure Functions を開発する | Microsoft Learn

また、Cosmos DB Emulator をインストールしておきます。SSL 証明書の準備などが不要な vNext がおすすめです（SwalowKit はこれに最適化されています）。

learn.microsoft.com

Docker を使用している場合は、以下のコマンドで起動できます。

docker run --detach --publish 8081:8081 --publish 1234:1234 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview

1. プロジェクトの初期化

npx swallowkit init my-app
cd my-app

初期化時、使用する CI/CD パイプライン（GitHub Actions or Azure Pipelines）、Cosmos DB のプラン（Free Tier or サーバーレス）、VNET 統合有無を選択します。これらの選択は、後から npx swallowkit provision コマンドで Azure にリソースをプロビジョニングする際に使用される IaC コード（Bicep）に反映されます。

初期化で作成されるプロジェクト構造はこんな感じです。

Next.js の初期状態をベースに、Bicep と Functions のコードを追加しています。

2. モデルの作成

実際の開発は、モデル（Zod スキーマ）の作成から始まります。

例えば、TODO アプリを作る場合、カテゴリーと TODO のモデルを作成します。

npx swallowkit create-model category todo

できあがったコードには最低限のフィールドしか入っていませんが、必要に応じてフィールドを追加していきます。

import { z } from 'zod';

export const category = z.object({
  id: z.string(),
  name: z.string().min(1).max(50),
  createdAt: z.string().optional(),
  updatedAt: z.string().optional(),
});

export type Category = z.infer<typeof category>;

カテゴリーを TODO の親として紐付ける場合は、このようにネストさせて定義します。

import { z } from 'zod';
import { category } from './category';

export const todo = z.object({
  id: z.string(),
  text: z.string().min(1).max(200),
  completed: z.boolean().default(false),
  category: category.optional(), // 親子関係はネストで表現
  createdAt: z.string().optional(),
  updatedAt: z.string().optional(),
});

export type Todo = z.infer<typeof todo>;

3. コードの自動生成

npx swallowkit scaffold category
npx swallowkit scaffold todo

これで、フロントエンドの画面に加え、BFF レイヤーと、Azure Functions バックエンドのコードが生成されます。

4. ローカル開発サーバーの起動

npx swallowkit dev

ローカルで Next.js と Azure Functions の両方が起動し、Cosmos DB Emulator に接続されます。ブラウザで http://localhost:3000 を開くと、生成された CRUD 画面が表示されます。

自動生成されたコードを参考にしたりカスタマイズしたりしながら、アプリを開発していきます。

5. Azure へのプロビジョニング

Azure にリソースを作成します。

新しく作るリソースグループ名を指定して、以下のコマンドを実行します。

npx swallowkit provision -g my-resource-group

これで、Azure Static Web Apps、Azure Functions、Cosmos DB がプロビジョニングされ、Next.js アプリが Azure Static Web Apps にデプロイされます。

6. ソースコードのプッシュ

GitHub または Azure Repos にソースコードをプッシュします。

SwallowKit でプロビジョニングされたリポジトリには GitHub Actions または Azure Pipelines のワークフローが自動生成されています。

GitHub Actions の場合はプッシュ後すぐに CI/CD パイプラインが実行されますが、必要なシークレットが未登録のためいったん止めるか失敗を待ちます。

7. シークレットの登録

provision コマンドの実行後、以下のようにソースコードのビルド・デプロイのための CI/CD パイプラインの実行に必要なシークレットのキー／値ペアが出力されるので、GitHub Actions または Azure Pipelines のシークレットとしてすぐに登録できます。

📝 Next Steps:
  1. Configure CI/CD secrets/variables:

     [AZURE_STATIC_WEB_APPS_API_TOKEN]
       abc123def456ghi789jkl012mno345pqr678stu901vwx234yz567890abcdef

     [AZURE_FUNCTIONAPP_NAME]
       func-my-swallowkit-functions-abc123

     [AZURE_FUNCTIONAPP_PUBLISH_PROFILE]
       <publishData><publishProfile profileName="func-my-swallowkit-functions-abc123" publishMethod="MSDeploy" publishUrl="func-my-swallowkit-functions-abc123.scm.azurewebsites.net:443" msdeploySite="func-my-swallowkit-functions-abc123" userName="$func-my-swallowkit-functions-abc123" userPWD="aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890" destinationAppUrl="https://func-my-swallowkit-functions-abc123.azurewebsites.net" SQLServerDBConnectionString="" mySQLDBConnectionString="" hostingProviderForumLink="" controlPanelLink="http://windows.azure.com" webSystem="WebSites"><databases /></publishProfile><publishProfile profileName="func-my-swallowkit-functions-abc123" publishMethod="ZipDeploy" publishUrl="func-my-swallowkit-functions-abc123.scm.azurewebsites.net:443" userName="$func-my-swallowkit-functions-abc123" userPWD="aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890" destinationAppUrl="https://func-my-swallowkit-functions-abc123.azurewebsites.net" SQLServerDBConnectionString="" mySQLDBConnectionString="" hostingProviderForumLink="" controlPanelLink="http://windows.azure.com" webSystem="WebSites"><databases /></publishProfile></publishData>

8. CI/CD パイプラインの実行

シークレットの登録後、GitHub Actions または Azure Pipelines のワークフローを再度実行します（GitHub Actions は手動でトリガーできるよう設定済みです！）。

これで、Azure Static Web Apps に Next.js アプリがデプロイされます。

9. アプリの確認

Azure Static Web Apps の URL にアクセスして、アプリが正しく動作していることを確認します。

おわりに・今後の展望

SwallowKit は、Azure 環境に最適化されたスキーマ駆動開発ツールキットで、Next.js アプリを Azure Static Web Apps にスタンドアロンモードでデプロイし、独立した Azure Functions バックエンドと接続します。

Zod スキーマを共有することで、フロントエンドからデータベースまで一貫した型安全性を保証できる点が最大の特徴です。SwallowKit を使用することで、アプリの全スタックをコードファーストで構築でき、Azure へのデプロイも簡単に行えます。

AI コーディングエージェントによる開発と組み合わせれば、爆速でクラウドで動作するアプリケーションを手に入れることができると思います。

このツールキット、コンセプトの企画は昨年9月頭くらいから始めてその後試行錯誤しながら作ってきてようやく形になったものです。

上記で紹介した基本機能は実装できていて、公開版（本記事執筆時点の最新版 v1.0.0-beta.4）に含まれています。

まだまだ粗削りな部分も多いですが、今後ブラッシュアップしながら、以下のような機能の追加もしていきたいと思っています：

  • フロントエンド・バックエンドの一環した 認証・認可のサポート
  • Next.js 初期化オプションへの対応
  • コーディングエージェント向けのコード生成カスタム指示のサポート
  • バックエンド（Azure Functions）の TypeScript 以外の言語への対応

もし触ってみた方がいらっしゃいましたら、感想やフィードバックをいただけると嬉しいです！

  1. Static Web Apps に Next.js をホストすると、バックエンドは Azure Functions ではなくカスタマイズ不可の専用 App Service 環境になります。↩