awslabs/amplify-workflow

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.

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

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 MUST ask which login method the user wants (email/password, social login, SAML, passwordless, etc.). Do not assume a default.
• 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)

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.

Step 1: Identify the Task Type

| Task | Go 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 |

Step 2: Backend Features

You MUST read the corresponding reference for each backend feature:

| Feature | Reference | When to Use | | ---------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | Authentication | auth-backend.md | Email/password, social login, MFA, SAML/OIDC | | Data Models | data-backend.md | GraphQL schema, DynamoDB, relationships, auth rules | | File Storage | storage-backend.md | S3 uploads/downloads, access rules | | Functions & API | functions-and-api.md | Lambda, custom resolvers, REST/HTTP APIs, calling from client | | AI Features | ai.md | Conversation, generation, AI tools via Bedrock (backend config + React/Next.js frontend) | | Geo, PubSub, CDK | advanced-features.md | Backend-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.

Step 3: Frontend Integration

After configuring backend resources, connect the frontend. Choose by platform and feature:

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

| Feature | Reference | | ------------------------- | ------------------------------------------- | | Auth UI & flows | auth-web.md | | Data CRUD & subscriptions | data-web.md | | Storage upload/download | storage-web.md |

Mobile (Flutter, Swift, Android):

| Feature | Reference | | ------------------------- | ------------------------------------------------- | | Auth UI & flows | auth-mobile.md | | Data CRUD & subscriptions | data-mobile.md | | Storage upload/download | storage-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.

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

| Package | Purpose | | -------------------------- | ------------------------------------------------------------------------------ | | @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 |

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.

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
• Enable CloudTrail and CloudWatch alarms for monitoring Amplify-deployed resources; enable access logging on S3, AppSync, and API Gateway
• Configure security headers for web apps — set CSP, HSTS, X-Frame-Options, and X-Content-Type-Options via customHeaders in amplify.yml
• Attach AWS WAF to public-facing AppSync APIs and API Gateway endpoints for defense in depth
• Enable throttling and rate limiting on API Gateway and AppSync APIs to prevent abuse
• Use IAM roles with ephemeral credentials for CI/CD pipelines and Lambda execution roles — never long-lived access keys
• Encrypt CloudWatch Logs groups with KMS (aws:kms) when they may contain PII, tokens, or secrets; enable log retention policies
• Enable AppSync schema validation and API Gateway request validators to reject malformed input at the edge
• Use ACM-managed TLS certificates for custom domains on Amplify Hosting — configure via customDomain in deployment config

Links

All documentation links use react as the default platform slug. Replace /react/ in any URL with your target framework:

| Framework | Slug | | ------------ | -------------- | | 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
• 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