Back to Details

aws-amplify

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

AWS Amplify Gen2

AWS Amplify Gen2

Build and deploy full-stack applications using AWS Amplify Gen2's TypeScript code-first approach. This skill covers backend resource creation, frontend integration across 8 frameworks, and deployment workflows.
使用AWS Amplify Gen2的TypeScript代码优先方法构建并部署全栈应用。本技能涵盖后端资源创建、8种框架的前端集成以及部署工作流。

Prerequisites

前提条件

  • Node.js ^18.19.0 || ^20.6.0 || >=22 and npm
  • AWS credentials configured (
    aws sts get-caller-identity
    succeeds)
  • For sandbox: 
    npx ampx --version
    returns a valid version
  • For mobile: Platform-specific tooling (Xcode, Android Studio, Flutter SDK)
  • Node.js ^18.19.0 || ^20.6.0 || >=22 及 npm
  • 已配置AWS凭证（
    aws sts get-caller-identity
    命令执行成功）
  • 沙箱环境：
    npx ampx --version
    返回有效版本
  • 移动开发：平台特定工具（Xcode、Android Studio、Flutter SDK）

Defaults & Assumptions

默认设置与假设

When the user does not specify a framework:
  • Web: You SHOULD default to React (Vite) and explain the choice.
  • Mobile: You MUST ask which platform the user wants (Flutter, Swift, Android, or React Native). There is no universal mobile default.
  • Neither specified: If the user says "build an app" without clarifying web vs. mobile, you MUST ask before proceeding.
  • Backend only: If only backend changes are requested and no frontend framework is mentioned, skip the frontend integration step entirely.
When the user does not specify tooling or strategy:
  • Package manager: You SHOULD default to npm unless the user specifies yarn or pnpm.
  • Language: You SHOULD default to TypeScript. Gen2 backends are TypeScript-only; frontends SHOULD follow the project's existing language.
  • Next.js: You SHOULD default to App Router unless the user specifies Pages Router.
  • React Native: Ask the user whether they use Expo or bare React Native CLI.
  • Auth: You SHOULD default to email/password as the login method unless the user specifies social login, SAML, or another provider.
  • Data authorization: default to 
    publicApiKey
     (
    allow.publicApiKey()
    ) — this is the starter template default. When auth is added, switch to owner-based (
    allow.owner()
    ) with 
    defaultAuthorizationMode: 'userPool'
    .
当用户未指定框架时：
  • Web端： 应默认使用React（Vite）并说明选择理由。
  • 移动端： 必须询问用户目标平台（Flutter、Swift、Android或React Native），无通用移动端默认选项。
  • 未指定类型： 如果用户仅说“构建应用”但未明确Web或移动端，必须先询问再继续。
  • 仅后端： 如果仅请求后端变更且未提及前端框架，完全跳过前端集成步骤。
当用户未指定工具或策略时：
  • 包管理器： 应默认使用npm，除非用户指定yarn或pnpm。
  • 语言： 应默认使用TypeScript。Gen2后端仅支持TypeScript；前端应遵循项目现有语言。
  • Next.js： 应默认使用App Router，除非用户指定Pages Router。
  • React Native： 询问用户使用Expo还是原生React Native CLI。
  • 认证： 应默认使用邮箱/密码作为登录方式，除非用户指定社交登录、SAML或其他提供商。
  • 数据授权： 默认使用**
    publicApiKey
    **（
    allow.publicApiKey()
    ）——这是启动模板的默认设置。添加认证后，切换为基于所有者的授权（
    allow.owner()
    ）并设置
    defaultAuthorizationMode: 'userPool'
    。

Quick Start — Route to the Right Reference

快速入门——跳转至正确参考文档

Step 0: Read Core Reference (ALWAYS)

步骤0：阅读核心参考文档（必须执行）

You MUST read the core reference for your target platform before reading any other reference file. These contain Gen2 detection, 
Amplify.configure()
placement per framework, sandbox commands, required packages, and directory structure rules — patterns needed for all tasks, not just new projects.
  • Web (React, Next.js, Vue, Angular, React Native): You MUST read core-web.md
  • Mobile (Flutter, Swift, Android): You MUST read core-mobile.md
  • Backend only (no frontend work): Skip to Step 1.
在阅读任何其他参考文件之前，必须先阅读目标平台的核心参考文档。这些文档包含Gen2检测、各框架下
Amplify.configure()
的放置位置、沙箱命令、所需包以及目录结构规则——这些是所有任务都需要的模式，不仅限于新项目。
  • Web端（React、Next.js、Vue、Angular、React Native）：必须阅读core-web.md
  • 移动端（Flutter、Swift、Android）：必须阅读core-mobile.md
  • 仅后端（无前端工作）：直接跳至步骤1。

Step 1: Identify the Task Type

步骤1：识别任务类型

TaskGo To
Create a new project→ scaffolding.md, then Step 2 and/or Step 3
Add or modify a backend feature→ Step 2 (Backend Features)
Connect frontend to existing backend→ Step 3 (Frontend Integration)
Deploy the application→ deployment.md
任务跳转至
创建新项目→ scaffolding.md，然后执行步骤2和/或步骤3
添加或修改后端功能→ 步骤2（后端功能）
将前端连接至现有后端→ 步骤3（前端集成）
部署应用→ deployment.md

Step 2: Backend Features

步骤2：后端功能

You MUST read the corresponding reference for each backend feature:
FeatureReferenceWhen to Use
Authenticationauth-backend.mdEmail/password, social login, MFA, SAML/OIDC
Data Modelsdata-backend.mdGraphQL schema, DynamoDB, relationships, auth rules
File Storagestorage-backend.mdS3 uploads/downloads, access rules
Functions & APIfunctions-and-api.mdLambda, custom resolvers, REST/HTTP APIs, calling from client
AI Featuresai.mdConversation, generation, AI tools via Bedrock (backend config + React/Next.js frontend)
Geo, PubSub, CDKadvanced-features.mdBackend-only: custom CDK stacks, overrides, custom outputs. Backend + frontend: Geo, PubSub, Face Liveness
Each backend feature file is self-contained. Load only what you need.
Routing note: These files apply for both adding and modifying features. Route to the same file whether the user says "add auth" or "change auth config" — each reference covers the full define surface.
必须为每个后端功能阅读对应的参考文档：
功能参考文档使用场景
认证auth-backend.md邮箱/密码、社交登录、MFA、SAML/OIDC
数据模型data-backend.mdGraphQL Schema、DynamoDB、关联关系、授权规则
文件存储storage-backend.mdS3上传/下载、访问规则
函数与APIfunctions-and-api.mdLambda、自定义解析器、REST/HTTP API、客户端调用
AI功能ai.md对话、生成、通过Bedrock实现的AI工具（后端配置 + React/Next.js前端）
地理服务、PubSub、CDKadvanced-features.md仅后端：自定义CDK堆栈、覆盖配置、自定义输出。后端+前端：地理服务、PubSub、人脸活体检测
每个后端功能文件都是独立的，仅加载所需内容。
路由说明： 这些文件适用于添加和修改功能。无论用户说“添加认证”还是“修改认证配置”，都跳转至同一文件——每个参考文档涵盖完整的定义范围。

Step 3: Frontend Integration

步骤3：前端集成

After configuring backend resources, connect the frontend. Choose by platform and feature:
Web (React, Next.js, Vue, Angular, React Native):
FeatureReference
Auth UI & flowsauth-web.md
Data CRUD & subscriptionsdata-web.md
Storage upload/downloadstorage-web.md
Mobile (Flutter, Swift, Android):
FeatureReference
Auth UI & flowsauth-mobile.md
Data CRUD & subscriptionsdata-mobile.md
Storage upload/downloadstorage-mobile.md
Note: AI and Functions frontend patterns are included in ai.md and functions-and-api.md respectively — they are not split into separate web/mobile files.
配置后端资源后，连接前端。根据平台和功能选择对应文档：
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和函数的前端模式分别包含在ai.md和functions-and-api.md中——它们不会拆分为单独的Web/移动端文件。

Core Concepts

核心概念

Amplify Gen2 Architecture

Amplify Gen2架构

  • Code-first: All backend resources defined in TypeScript under 
    amplify/
  • Main config: 
    amplify/backend.ts
    imports and combines all resources via 
    defineBackend()
  • Resource files: 
    amplify/auth/resource.ts
    , 
    amplify/data/resource.ts
    , 
    amplify/storage/resource.ts
    , 
    amplify/functions/<name>/resource.ts
  • Generated output: 
    amplify_outputs.json
    — consumed by frontend 
    Amplify.configure()
    . Gitignored — generated by 
    npx ampx sandbox
    (local dev) or 
    npx ampx pipeline-deploy
    (CI/CD), never committed.
  • 代码优先： 所有后端资源在
    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）生成，切勿提交至Git。

Directory Structure

目录结构

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 — DO NOT edit or commit (gitignored)
└── package.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

Key APIs

关键API

PackagePurpose
@aws-amplify/backend
defineAuth
, 
defineData
, 
defineStorage
, 
defineFunction
, 
defineBackend
aws-amplify
Frontend: 
Amplify.configure()
, 
generateClient()
, auth/data/storage APIs
@aws-amplify/ui-react
Pre-built UI: 
<Authenticator>
, 
<StorageBrowser>
@aws-amplify/ui-react-ai
AI UI: 
<AIConversation>
, 
useAIConversation
包用途
@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

Documentation & Resource Verification

文档与资源验证

When you need AWS documentation (advanced CDK constructs, service limits, provider-specific auth config):
  1. If AWS documentation tools are available (e.g., via AWS MCP), you SHOULD use them to search and retrieve relevant documentation pages.
  2. If AWS documentation tools are unavailable, you MUST fall back to web search or the 
    aws
    CLI for resource verification.
Why conditional: Amplify Gen2 is code-first — the primary workflow is editing TypeScript files and running 
npx ampx
commands. AWS MCP tools are useful for post-deployment verification but are not required.
当需要AWS文档（高级CDK构造、服务限制、提供商特定认证配置）时：
  1. 如果AWS文档工具可用（例如通过AWS MCP），应使用这些工具搜索并检索相关文档页面。
  2. 如果AWS文档工具不可用，必须通过网页搜索或
    aws
    CLI进行资源验证。
为什么有条件： Amplify Gen2是代码优先的——主要工作流是编辑TypeScript文件并运行
npx ampx
命令。AWS MCP工具对部署后的验证有用，但不是必需的。

Security Considerations

安全注意事项

  • Use 
    secret()
    for all credentials and API keys — never hardcode or use plain environment variables for sensitive values
  • Review 
    allow.guest()
    exposure carefully — guest access is enabled by default and grants unauthenticated users access to IAM-authorized resources
  • Scope IAM policies to specific resource ARNs — avoid 
    resources: ['*']
    in production
  • Never log secrets or include them in error messages
  • 所有凭证和API密钥使用
    secret()
    ——切勿硬编码或使用普通环境变量存储敏感值
  • 仔细检查
    allow.guest()
    的暴露范围——访客访问默认启用，会授予未认证用户访问IAM授权资源的权限
  • 将IAM策略限定为特定资源ARN——生产环境中避免使用
    resources: ['*']
  • 切勿记录密钥或在错误信息中包含密钥

Links

链接

All documentation links use 
react
as the default platform slug. Replace 
/react/
in any URL with your target framework:
FrameworkSlug
React
react
Next.js
nextjs
Vue
vue
Angular
angular
React Native
react-native
Flutter
flutter
Swift
swift
Android
android
所有文档链接默认使用
react
作为平台路径。将URL中的
/react/
替换为目标框架的路径：
框架路径标识
React
react
Next.js
nextjs
Vue
vue
Angular
angular
React Native
react-native
Flutter
flutter
Swift
swift
Android
android