aws-amplify

AWS Amplify Gen2

使用 AWS Amplify Gen2 的 TypeScript code-first（程式碼優先）架構建立與部署全端應用程式。本 Skill 涵蓋後端資源建立、8 種框架的前端整合以及部署工作流程。

事前準備

• Node.js ^18.19.0 || ^20.6.0 || >=22 及 npm
• 已設定 AWS 憑證（執行 aws sts get-caller-identity 成功）
• 沙盒環境（Sandbox）：npx ampx --version 回傳有效版本
• 行動端（Mobile）：特定平台的開發工具（Xcode、Android Studio、Flutter SDK）

預設值與假設

當使用者未指定框架時：

• Web： 預設使用 React (Vite) 並說明選擇原因。
• Mobile（行動端）： 詢問使用哪種平台（Flutter、Swift、Android 或 React Native）— 行動端沒有通用的預設選項，盲目猜測會造成無謂的重複嘗試。
• 皆未指定： 若使用者僅表示「建立 App」而未澄清是 Web 還是 Mobile，請在開始前先詢問 — 框架選擇會影響後續的每一個步驟。
• 僅限後端： 若僅要求修改後端且未提及前端框架，請直接跳過前端整合步驟。

當使用者未指定工具或策略時：

• 套件管理工具（Package manager）： 預設使用 npm，除非使用者指定 yarn 或 pnpm。
• 語言： 預設使用 TypeScript。Gen2 後端僅支援 TypeScript；前端應跟隨專案現有的語言。
• Next.js： 預設使用 App Router，除非使用者指定 Pages Router。
• React Native： 詢問使用者是使用 Expo 還是 純 React Native CLI（bare）。
• 身份驗證（Auth）： 您必須詢問使用者需要的登入方式（Email/密碼、社群登入、SAML、無密碼登入等）。切勿自行假設預設值。
• 資料授權（Data authorization）： 預設為 publicApiKey (allow.publicApiKey()) — 這是入門範本的預設設定。新增身份驗證後，請切換為基於擁有者（owner-based） 的 (allow.owner())，並設定 defaultAuthorizationMode: 'userPool'。

快速入門 — 導向對應的參考文件

步驟 1：確認任務類型

任務	參考章節 / 文件
建立新專案	→ scaffolding.md，接著執行步驟 2 及/或步驟 3
新增或修改後端功能	→ 步驟 2（後端功能）
將前端連接至現有後端	→ 步驟 3（前端整合）
部署應用程式	→ deployment.md

步驟 2：後端功能

請針對您需要的各項後端功能參閱對應的參考文件：

功能	參考文件	時機
身份驗證（Authentication）	auth-backend.md	Email/密碼、社群登入、MFA、SAML/OIDC
資料模型（Data Models）	data-backend.md	GraphQL schema、DynamoDB、關聯性、授權規則
檔案儲存（File Storage）	storage-backend.md	S3 上傳/下載、存取規則
Function 與 API	functions-and-api.md	Lambda、自訂 Resolver、REST/HTTP API、從用戶端呼叫
AI 功能	ai.md	對話、生成、透過 Bedrock 使用 AI 工具 (後端設定 + React/Next.js 前端)
Geo、PubSub、CDK	geo-pubsub-cdk.md	僅限後端：自訂 CDK Stack、覆寫（Overrides）、自訂輸出。後端 + 前端：Geo、PubSub、Face Liveness

每個後端功能文件皆為獨立內容。請僅載入您所需的內容。

路由說明： 無論是新增還是修改功能，這些文件皆適用。無論使用者說「新增 auth」還是「修改 auth 設定」，都請導向同一個文件 — 每個參考文件均涵蓋完整的 define 介面。

步驟 3：前端整合

完成後端資源設定後，請連接前端。依平台與功能選擇：

Web (React, Next.js, Vue, Angular, React Native)：

功能	參考文件
Auth UI 與流程	auth-web.md
Data CRUD 與訂閱	data-web.md
Storage 上傳/下載	storage-web.md

Mobile (Flutter, Swift, Android)：

功能	參考文件
Auth UI 與流程	auth-mobile.md
Data CRUD 與訂閱	data-mobile.md
Storage 上傳/下載	storage-mobile.md

注意： AI 與 Function 的前端設計模式已分別包含在 ai.md 與 functions-and-api.md 中 — 它們並未拆分為獨立的 Web/Mobile 文件。

核心概念

Amplify Gen2 架構

• Code-first（程式碼優先）： 所有後端資源皆在 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 忽略（Gitignored） — 此檔案由 npx ampx sandbox（本機開發）或 npx ampx pipeline-deploy（CI/CD）自動產生，切勿 Commit 提交。

目錄結構

amplify/ 與 src/ 必須同屬於專案根目錄下的同級目錄 — 若放在不同的目錄層級會導致沙盒（Sandbox）偵測失敗。（例外：在 Monorepo 中，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      # 自動產生且已 Git 忽略 — 請勿手動編輯或提交
└── package.json

主要 API

套件（Package）	用途
@aws-amplify/backend	defineAuth, defineData, defineStorage, defineFunction, defineBackend
aws-amplify	前端：Amplify.configure(), generateClient(), auth/data/storage 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 專案 — 請勿繼續執行（需要獨立的遷移 Skill）。

前端設定

匯入產生的輸出檔，並在您框架的正確進入點中設定 Amplify。若放在錯誤的檔案中會導致靜默失敗 — Amplify API 呼叫會回傳 undefined 或空值且不會拋出錯誤。

警告： amplify_outputs.json 必須存在應用程式才能編譯 — 若缺少此檔案，建置會因為模組找不到（module-not-found）而失敗。請先執行 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 是伺服器元件（Server Component）。請改用下方展示的 ConfigureAmplifyClientSide 用戶端元件（Client Component）模式。

{ 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;
}

在您的根佈局（Root Layout）中匯入：

// 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 或 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 套件（它是 amplify-js 的一部分，而非原生 Mobile SDK）。所有 Web API 皆適用於 RN，並加上以下補充。

必要套件

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

`@react