aws-amplify

What this skill does

# 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:** Default to **React** (Vite) and explain the choice.
- **Mobile:** Ask which platform (Flutter, Swift, Android, or React Native) —
  there is no universal mobile default, so guessing leads to wasted effort.
- **Neither specified:** If the user says "build an app" without clarifying web
  vs. mobile, ask before proceeding — the framework choice affects every
  subsequent step.
- **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:** Default to **npm** unless the user specifies yarn or pnpm.
- **Language:** Default to **TypeScript**. Gen2 backends are TypeScript-only;
  frontends should follow the project's existing language.
- **Next.js:** Default to **App Router** unless the user specifies Pages Router.
- **React Native:** Ask whether the user uses **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 1: Identify the Task Type

| Task                                     | Go To                                                                    |
| ---------------------------------------- | ------------------------------------------------------------------------ |
| **Create a new project**                 | → [scaffolding.md](references/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](references/deployment.md)                              |

### Step 2: Backend Features

Read the corresponding reference for each backend feature you need:

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

**Mobile** (Flutter, Swift, Android):

| Feature                   | Reference                                         |
| ------------------------- | ------------------------------------------------- |
| Auth UI & flows           | [auth-mobile.md](references/auth-mobile.md)       |
| Data CRUD & subscriptions | [data-mobile.md](references/data-mobile.md)       |
| Storage upload/download   | [storage-mobile.md](references/storage-mobile.md) |

> **Note:** AI and Functions frontend patterns are included in
> [ai.md](references/ai.md) and
> [functions-and-api.md](references/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

`amplify/` and `src/` must be siblings under the project root — placing
them at different directory levels breaks sandbox detection. (Exception: in monorepos, `amplify/` may be in a `packages/` subdirectory — the key is that `amplify_outputs.json` must be accessible from the frontend entry point.)

```text
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
```

### 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` |

## Framework Setup

These patterns apply to **every** web task — not just new projects. Verify
each one before implementing any feature.

### Gen2 Detection

Before modifying any code, check if the project is already Gen2:

1. `amplify/` directory exists with `backend.ts`
2. `@aws-amplify/backend` in `package.json` devDependencies

If both are true, the project is already Gen2 — skip to feature
implementation. If `amplify/.config/` exists instead, this is a Gen1
project — do not proceed (requires separate migration skill).

### Frontend Configuration

Import the generated outputs and configure Amplify in the **correct entry
point** for your framework. Placing this in the wrong file causes silent
failures — Amplify API calls return undefined or empty responses with no error.

**WARNING:** `amplify_outputs.json` must exist before the app c