AWS Amplify Gen2

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)

Defaults & Assumptions

• 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.

• 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'

  .

Quick Start — Route to the Right Reference

Step 0: Read Core Reference (ALWAYS)

Amplify.configure()

• 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.

Step 1: Identify the Task Type

Step 2: Backend Features

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.

Step 3: Frontend Integration

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.

Core Concepts

Amplify Gen2 Architecture

• 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.

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

Key APIs

@aws-amplify/backend

defineAuth

defineData

defineStorage

defineFunction

defineBackend

aws-amplify

Amplify.configure()

generateClient()

@aws-amplify/ui-react

<Authenticator>

<StorageBrowser>

@aws-amplify/ui-react-ai

<AIConversation>

useAIConversation

Documentation & Resource Verification

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.

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

Links

All documentation links use

react

as the default platform slug. Replace

/react/

in any URL with your target framework:

react

nextjs

vue

angular

react-native

flutter

swift

android

• Amplify Docs for LLMs
• Amplify Docs
• Gen2 Docs
• Getting Started
• Quickstart
• Account Setup
• How Amplify Works
• Core Concepts
• Build a Backend
• Deploy and Host
• Troubleshooting
• CLI Commands
• Amplify Outputs
• Project Structure
• Amplify UI