aws-amplify

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 かモバイルかを明確にせずに「アプリを作る」と言った場合は、作業を進める前に確認してください。フレームワークの選択は、その後のすべての手順に影響します。
• バックエンドのみ： バックエンドの変更のみが依頼され、フロントエンドのフレームワークが言及されていない場合は、フロントエンド統合の手順を完全に省略してください。

ユーザーがツールや方針を指定していない場合：

• パッケージマネージャー： ユーザーが 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

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

振り分けに関する注意： これらのファイルは、機能の追加と変更の両方に適用されます。ユーザーが「認証を追加する」と言っても「認証設定を変更する」と言っても、同じファイルを参照してください。各リファレンスでは、定義に関する内容をすべて扱っています。

ステップ 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／モバイル用の別ファイルには分かれていません。

コアコンセプト

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() で使用します。Git の追跡対象外であり、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/                      # Frontend code
├── amplify_outputs.json      # Generated, gitignored — never edit or commit
└── 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. package.json の devDependencies に @aws-amplify/backend がある

両方に該当する場合、プロジェクトはすでに Gen2 です。機能の実装に進んでください。代わりに amplify/.config/ がある場合、これは Gen1 プロジェクトです。作業を進めないでください（別途、移行スキルが必要です）。

フロントエンドの設定

生成された出力をインポートし、フレームワークの正しいエントリーポイントで Amplify を設定してください。間違ったファイルに配置すると、エラーが表示されないまま失敗することがあります。Amplify の API 呼び出しが、エラーなしで undefined または空の応答を返します。

警告： アプリをコンパイルする前に 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：

重要： App Router の layout.tsx はサーバーコンポーネントです。代わりに、以下の 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 ではファイルごとに設定します。

認証コンテキストには、layout.tsx の <Authenticator.Provider> が必要です。

React Native

React Native では、Web フレームワークと同じ aws-amplify JS パッケージを使用します（ネイティブモバイル SDK ではなく amplify-js の一部です）。以下の追加事項を除き、すべての 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';  // MUST be first
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';  // MUST be first
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

Astro では Amplify はクライアントサイド専用です。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 — no Amplify imports here
---
<html>
  <body>
    <AuthenticatedApp client:only="react" />
  </body>
</html>

必ず client:only="react" を使用してください（SSR のハイドレーションエラーを避けるため、client:load は使用しないでください）。

リンク

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

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

• LLM 向け Amplify ドキュメント
• Amplify ドキュメント
• Amplify の仕組み
• CLI コマンド
• React クイックスタート
• Next.js クイックスタート
• Angular クイックスタート
• Vue クイックスタート
• React Native クイックスタート