AWS Amplify Gen2

AWS Amplify Gen2 の TypeScript コードファースト手法を使用して、フルスタック アプリケーションを構築・デプロイします。このスキルは、バックエンド リソースの作成、8 つのフレームワークにまたがるフロントエンド統合、 およびデプロイメント ワークフローをカバーしています。

前提条件

• Node.js ^18.19.0 || ^20.6.0 || >=22 および npm
• AWS 認証情報の設定 (aws sts get-caller-identity が成功する)
• サンドボックス用: npx ampx --version が有効なバージョンを返す
• モバイル用: プラットフォーム固有のツール (Xcode、Android Studio、Flutter SDK)

デフォルト & 前提条件

ユーザーがフレームワークを指定していない場合:

• Web: React (Vite) をデフォルトにして、その選択を説明してください。
• モバイル: どのプラットフォーム (Flutter、Swift、Android、React Native) を使用するか 尋ねてください — ユーザーの努力が無駄になるため、推測は避けてください。
• どちらも指定されない: ユーザーが web と mobile を明確にせずに「アプリを構築する」と言った場合、 進める前に尋ねてください — フレームワークの選択は後続のすべてのステップに影響します。
• バックエンドのみ: バックエンド変更のみが要求されており、フロントエンド フレームワークが記載されていない場合、フロントエンド統合ステップはスキップしてください。

ユーザーがツーリングまたは戦略を指定していない場合:

• パッケージ マネージャー: ユーザーが yarn または pnpm を指定していない限り、npm をデフォルトにします。
• 言語: TypeScript をデフォルトにします。Gen2 バックエンドは TypeScript のみです。 フロントエンドはプロジェクトの既存言語に従うべきです。
• Next.js: ユーザーが Pages Router を指定していない限り、App Router をデフォルトにします。
• React Native: ユーザーが Expo または bare React Native CLI を使用しているかを尋ねてください。
• 認証: ユーザーがどのログイン方法を望むか (メール/パスワード、ソーシャル ログイン、 SAML、パスワードレス など) を必ず尋ねてください。デフォルトを仮定しないでください。
• データ認可: publicApiKey (allow.publicApiKey()) をデフォルトにします — これはスターター テンプレートのデフォルトです。 認証が追加されたら、所有者ベース (allow.owner()) および defaultAuthorizationMode: 'userPool' に切り替えます。

クイック スタート — 正しいリファレンスへのルーティング

ステップ 1: タスク タイプの特定

タスク	参照先
新しいプロジェクトの作成	→ scaffolding.md、その後ステップ 2 または 3
バックエンド機能の追加または変更	→ ステップ 2 (バックエンド機能)
既存バックエンドへのフロントエンド接続	→ ステップ 3 (フロントエンド統合)
アプリケーションのデプロイ	→ deployment.md

ステップ 2: バックエンド機能

必要なバックエンド機能ごとに対応するリファレンスを読んでください:

機能	リファレンス	使用時期
認証	auth-backend.md	メール/パスワード、ソーシャル ログイン、MFA、SAML/OIDC
データ モデル	data-backend.md	GraphQL スキーマ、DynamoDB、リレーションシップ、認可ルール
ファイル ストレージ	storage-backend.md	S3 アップロード/ダウンロード、アクセス ルール
関数 & API	functions-and-api.md	Lambda、カスタム リゾルバー、REST/HTTP API、クライアントからの呼び出し
AI 機能	ai.md	会話、生成、Bedrock 経由の AI ツール (バックエンド設定 + React/Next.js フロントエンド)
Geo、PubSub、CDK	geo-pubsub-cdk.md	バックエンドのみ: カスタム CDK スタック、オーバーライド、カスタム出力。バックエンド + フロントエンド: Geo、PubSub、Face Liveness

各バックエンド機能ファイルは独立しています。必要なもののみを読み込んでください。

ルーティング注: これらのファイルは機能の 追加 と 変更 の両方に適用されます。 ユーザーが「認証を追加する」または「認証設定を変更する」と言った場合でも、 同じファイルにルーティングしてください。各リファレンスは完全な define サーフェスをカバーしています。

ステップ 3: フロントエンド統合

バックエンド リソースを設定した後、フロントエンドに接続します。 プラットフォームと機能により選択してください:

Web (React、Next.js、Vue、Angular、React Native):

機能	リファレンス
認証 UI & フロー	auth-web.md
データ CRUD & サブスクリプション	data-web.md
ストレージ アップロード/ダウンロード	storage-web.md

モバイル (Flutter、Swift、Android):

機能	リファレンス
認証 UI & フロー	auth-mobile.md
データ CRUD & サブスクリプション	data-mobile.md
ストレージ アップロード/ダウンロード	storage-mobile.md

注: AI および Functions フロントエンド パターンは ai.md および functions-and-api.md に含まれています。これらは 別の web/mobile ファイルに分割 されていません。

コア コンセプト

Amplify Gen2 アーキテクチャ

• コードファースト: すべてのバックエンド リソースは amplify/ の下で TypeScript で定義されます
• メイン設定: amplify/backend.ts は defineBackend() を介してすべてのリソースをインポートして結合します
• リソース ファイル: amplify/auth/resource.ts、amplify/data/resource.ts、 amplify/storage/resource.ts、amplify/functions/<name>/resource.ts
• 生成出力: amplify_outputs.json — フロントエンド Amplify.configure() で使用されます。 .gitignored — npx ampx sandbox (ローカル開発) または npx ampx pipeline-deploy (CI/CD) で生成され、 コミットされません。

ディレクトリ構造

amplify/ と src/ はプロジェクト ルートの兄弟である必要があります。 それらを異なるディレクトリ レベルに配置するとサンドボックス検出が破損します。 (例外: モノレポでは amplify/ は packages/ サブディレクトリに配置できます。 重要なのは amplify_outputs.json がフロントエンド エントリ ポイントからアクセス可能である必要があることです。)

project-root/
├── amplify/
│   ├── backend.ts            # defineBackend({ auth, data, ... })
│   ├── auth/resource.ts      # defineAuth({ ... })
│   ├── data/resource.ts      # defineData({ schema })
│   ├── storage/resource.ts   # defineStorage({ ... })
│   └── functions/
│       └── my-func/
│           ├── resource.ts   # defineFunction({ ... })
│           └── handler.ts    # export const handler = ...
├── src/                      # フロントエンド コード
├── amplify_outputs.json      # 生成、gitignored — 編集またはコミットしないでください
└── package.json

主要 API

パッケージ	目的
@aws-amplify/backend	defineAuth、defineData、defineStorage、defineFunction、defineBackend
aws-amplify	フロントエンド: Amplify.configure()、generateClient()、認証/データ/ストレージ API
@aws-amplify/ui-react	事前構築 UI: <Authenticator>、<StorageBrowser>
@aws-amplify/ui-react-ai	AI UI: <AIConversation>、useAIConversation

フレームワーク セットアップ

これらのパターンは すべての web タスク に適用されます — 新規プロジェクトのみではありません。 機能を実装する前に各パターンを確認してください。

Gen2 検出

コードを変更する前に、プロジェクトが既に Gen2 であるかを確認してください:

1. amplify/ ディレクトリが存在し、backend.ts がある
2. @aws-amplify/backend が package.json の devDependencies にある

両方が真の場合、プロジェクトは既に Gen2 です — 機能実装に進んでください。 amplify/.config/ が代わりに存在する場合、これは Gen1 プロジェクトです — 進めないでください (個別の移行スキルが必要です)。

フロントエンド構成

生成された出力をインポートし、フレームワークの 正しいエントリ ポイント で Amplify を設定します。 これを間違ったファイルに配置すると、サイレント障害が発生します — Amplify API 呼び出しは未定義または 空のレスポンスを返し、エラーは表示されません。

警告: amplify_outputs.json がアプリのコンパイル前に存在する必要があります — これがないと、 ビルドはモジュール見つからないエラーで失敗します。 最初に npx ampx sandbox (または npx ampx sandbox --once) を実行して生成してください。 正しなシーケンスについては scaffolding.md を参照してください。

React (Vite) — src/main.tsx:

import { Amplify } from 'aws-amplify';
import outputs from '../amplify_outputs.json';
Amplify.configure(outputs);

Next.js (App Router) — app/layout.tsx:

重要: layout.tsx は App Router のサーバー コンポーネントです。 代わりに以下の ConfigureAmplifyClientSide クライアント コンポーネント パターンを使用してください。

{ ssr: true } は Next.js のみ のオプション (Vue、Angular、React SPA では不要)。 App Router と Pages Router の両方がこれを使用しますが、異なる方法で適用されます:

• App Router — ConfigureAmplifyClientSide クライアント コンポーネントでグローバルに設定
• Pages Router — サーバー側アクセスが必要なファイルごとに設定

Next.js App Router: クライアント側設定

Next.js App Router では、ブラウザ側の操作のために Amplify を設定するための 専用クライアント コンポーネントが必要です:

// components/ConfigureAmplifyClientSide.tsx
"use client";
import { Amplify } from "aws-amplify";
import outputs from "@/amplify_outputs.json";

Amplify.configure(outputs, { ssr: true });

export default function ConfigureAmplifyClientSide() {
  return null;
}

ルート レイアウトにインポートしてください:

// app/layout.tsx
import ConfigureAmplifyClientSide from "@/components/ConfigureAmplifyClientSide";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <ConfigureAmplifyClientSide />
        {children}
      </body>
    </html>
  );
}

理由: App Router では、layout.tsx はサーバー コンポーネントです。 クライアント コンポーネントは Amplify.configure() をブラウザで実行する必要があります。 これがないと、「Auth UserPool not configured」エラーが発生します。

Vue — src/main.js:

import { Amplify } from 'aws-amplify';
import outputs from '../amplify_outputs.json';
Amplify.configure(outputs);

Angular — src/main.ts:

import { Amplify } from 'aws-amplify';
import outputs from '../amplify_outputs.json';
Amplify.configure(outputs);

Next.js Pages Router

Pages Router は _app.tsx に { ssr: true } を必要としません。代わりに、 サーバー側アクセスが必要なファイルごとに設定してください:

// pages/api/protected.ts or getServerSideProps
import { Amplify } from 'aws-amplify';
import outputs from '@/amplify_outputs.json';
Amplify.configure(outputs, { ssr: true });

主な違い: App Router はグローバル クライアント コンポーネントを使用します。 Pages Router はファイルごとに設定します。

<Authenticator.Provider> は認証コンテキストのために layout.tsx で必須です。

React Native

React Native は web フレームワークと同じ aws-amplify JS パッケージを使用します (amplify-js の一部であり、ネイティブ モバイル SDK ではありません)。 すべての web API が RN に以下の追加とともに適用されます。

必須パッケージ

npm install aws-amplify @aws-amplify/react-native \
  @react-native-async-storage/async-storage \
  react-native-get-random-values

@react-native-async-storage/async-storage は 必須 です — Amplify SDK はそれを トークンの永続化に使用し、これがないと実行時に失敗します。

エントリ ポイントの設定

プラグイン登録は必要ありません — 設定のみです。

React Native (Expo) — App.tsx:

import 'react-native-get-random-values';  // 最初である必要があります
import { Amplify } from 'aws-amplify';
import outputs from './amplify_outputs.json';
Amplify.configure(outputs);

React Native (Bare CLI) — index.js (AppRegistry.registerComponent の前):

import 'react-native-get-random-values';  // 最初である必要があります
import { Amplify } from 'aws-amplify';
import outputs from './amplify_outputs.json';
Amplify.configure(outputs);

React Native の落とし穴

• インポート順序: react-native-get-random-values はエントリ ファイルの 最初 のインポートである必要があります。aws-amplify の前です。 順序を逆にすると、実行時に暗号化の障害が発生します。
• AsyncStorage の欠落: @react-native-async-storage/async-storage がないと、 認証トークンが永続化されず、ユーザーはアプリ再起動のたびに再認証が必要です。

SvelteKit

クライアント フックス ファイルで Amplify を設定してください:

// src/hooks.client.ts
import { Amplify } from 'aws-amplify';
import outputs from '../amplify_outputs.json';

Amplify.configure(outputs);

注: Svelte 用の @aws-amplify/ui-* コンポーネントは存在しません。 コア API を直接使用してください。

サポートされていないフレームワーク (Astro、Solid など)

Amplify の公式サポートがないフレームワークの場合:

1. npm create amplify@latest -y を使用してバックエンドをスキャフォールドします (任意のプロジェクトで動作します)
2. クライアント側コンポーネント (ビルド時ではなく) 内で Amplify を設定します

Astro

Amplify は Astro では クライアント側のみ です。React コンポーネントを作成します (Astro 構文なし):

// src/components/AuthenticatedApp.tsx
import { Amplify } from 'aws-amplify';
import { Authenticator } from '@aws-amplify/ui-react';
import outputs from '../amplify_outputs.json';

Amplify.configure(outputs);

export default function AuthenticatedApp() {
  return (
    <Authenticator>
      {({ signOut, user }) => <main>Hello {user?.username}</main>}
    </Authenticator>
  );
}

client:only で Astro ページで使用します:

---
// src/pages/index.astro — ここに Amplify インポートはありません
---
<html>
  <body>
    <AuthenticatedApp client:only="react" />
  </body>
</html>

client:only="react" を使用する必須 (NOT client:load) SSR ハイドレーション エラーを回避するためです。

リンク

すべてのドキュメント リンクは react をデフォルト プラットフォーム スラッグとして使用します。 任意の URL の /react/ をターゲット フレームワークに置き換えてください:

フレームワーク	スラッグ
React	react
Next.js	nextjs
Vue	vue
Angular	angular
React Native	react-native
Flutter	flutter
Swift	swift
Android	android

• Amplify Docs for LLMs
• Amplify Docs
• How Amplify Works
• CLI Commands
• React Quickstart
• Next.js Quickstart
• Angular Quickstart
• Vue Quickstart
• React Native Quickstart