AWS Amplify

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

Step 2: Backend Features

Read the corresponding reference for each backend feature you need:

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):

Mobile (Flutter, Swift, Android):

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

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

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

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