aws-blocks

AWS Blocks アプリケーション開発

パッケージの命名規則： すべてのパッケージは @aws-blocks スコープで公開されています（例：@aws-blocks/core、@aws-blocks/blocks、@aws-blocks/bb-kv-store）。

概要

AWS Blocks は、Building Block に CDK、SDK、ローカルモックをまとめ、単一の API として提供する Infrastructure-from-Code フレームワークです。ストレージ、認証、リアルタイム通信、バックグラウンドジョブ、ファイル管理、AI／検索、メール、オブザーバビリティを網羅する 18 種類以上の Building Block を提供し、すべて AWS 認証情報なしでローカルに動作します。

主な特徴：

• 1 つの aws-blocks/ ディレクトリでバックエンド全体を定義します
• フロントエンドのインポートは完全に型付けされており、クライアントの生成は不要です
• すべての Building Block は AWS なしでローカルに動作します（モックは .bb-data/ に保存されます）
• 最小権限の認証情報を使い、npm run sandbox で一時的な個別テスト環境を、npm run deploy で長期間利用する環境をデプロイします

新しいプロジェクトのスキャフォールディング

npx @aws-blocks/create-blocks-app my-app
cd my-app

既存のプロジェクトに AWS Blocks を追加するには：

npx @aws-blocks/create-blocks-app .

既存のプロジェクトを検出し、コードと並ぶワークスペースとして aws-blocks/ を追加します。

Amplify Gen 2 プロジェクトに AWS Blocks を追加するには：

npx @aws-blocks/create-blocks-app .

CLI が amplify/backend.ts を検出すると、AWS Blocks を Amplify バックエンドに自動的に統合します。

特定のテンプレートを指定するには：

npx @aws-blocks/create-blocks-app my-app --template demo
cd my-app

利用可能なテンプレート

テンプレート	説明
default	基本的なアプリケーションアーキテクチャとパターンの実演に役立つ、基本認証、データの永続化、リアルタイム機能を備えた Vite + lit-html のスターターアプリ（--template を省略した場合に使用）
bare	単一の「hello world」API メソッドとシンプルなフロントエンドを備えた Vite + lit-html のスターター
react	単一の API エンドポイントと型付けされた React フロントエンドを備えた React + Vite のスターター
backend	バックエンドのみ。フロントエンドはなく、単一のエンドポイントを備えた AWS Blocks API のみ
demo	AuthBasic、KVStore、DistributedTable、Zod スキーマ、インデックス、認証で保護された CRUD を備えた Todo アプリ
auth-cognito	ロール、デバイス管理、Authenticator UI を備えた、AuthCognito によるパスワードレスのメール OTP 機能一式
nextjs	AWS Blocks バックエンド統合（SSR + Server Components）を備えた Next.js + React のスターター

開発ワークフロー

スキャフォールディング後、開発ワークフロー全体については node_modules/@aws-blocks/blocks/README.md を参照してください。以下の内容が含まれます。

• 基本概念（アーキテクチャ、Building Block の選択）
• プロジェクト構成と Scope の整理
• エラー処理のパターン
• スキーマ検証
• ローカル開発
• ベストプラクティスとよくある間違い
• デプロイ用 IAM ロールの設定とセキュリティガイダンス

特定の Building Block を実装する際は、詳細な API リファレンスとして、そのパッケージの README を参照してください（例：node_modules/@aws-blocks/bb-kv-store/README.md）。これらは、インストール済みバージョンの正式なドキュメントです。

セキュリティに関する考慮事項

• 公開すべきでないすべてのメソッドで await auth.requireAuth(context) を使用してください。ApiNamespace のメソッドはデフォルトで認証されません
• API キーと認証情報には new AppSetting(scope, id, { secret: true }) を使用してください。ハードコードしたり、.env ファイルを使用したりしないでください
• ユーザーデータを受け付ける KVStore/AppSetting には必ずスキーマを設定してください。RPC レイヤーは構造を検証しますが、ビジネスロジックは検証しません
• 範囲の広い * IAM ポリシーを追加しないでください。各ビルディングブロックは、それぞれのリソースに限定した最小権限をすでに付与しています
• FileBucket の blockPublicAccess は変更しないでください。代わりに CloudFront 経由で公開ファイルを配信してください
• 本番環境では CORS_ALLOWED_ORIGINS を明示的に設定し、ワイルドカードは避けてください
• クロスドメイン環境にデプロイする場合は、認証コンストラクターに crossDomain: true を渡してください（SameSite=None; Secure; Partitioned が有効になります）
• 本番環境のアラートには、Hosting で monitoring: { enabled: true, snsTopicArn: '...' } を有効にしてください
• 外部公開アプリには、CDK 経由で WAF と API Gateway のスロットリングを追加してください。これらはデフォルトでは含まれていません
• Logger はシリアライズの安全性（循環参照、型変換）を提供しますが、機密情報はマスキングしません。生の認証情報、トークン、シークレットを Logger のメソッドに渡さないでください。ログに記録する前に、コンテキストオブジェクトをサニタイズしてください