│ ├── 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 can
compile — without it, the build fails with a module-not-found error.
Run `npx ampx sandbox` (or `npx ampx sandbox --once`) first to
generate it. See [scaffolding.md](references/scaffolding.md) for the correct sequence.

**React (Vite)** — `src/main.tsx`:

```typescript
import { Amplify } from 'aws-amplify';
import outputs from '../amplify_outputs.json';
Amplify.configure(outputs);

Next.js (App Router) — app/layout.tsx:

Important: layout.tsx is a server component in App Router. Use the ConfigureAmplifyClientSide client component pattern below instead.

{ ssr: true } is a Next.js-only option (not needed by Vue, Angular, or React SPA). Both App Router and Pages Router use it, but apply it differently:

• App Router — set globally in ConfigureAmplifyClientSide client component
• Pages Router — set per-file where server-side access is needed

Next.js App Router: Client-Side Configuration

Next.js App Router requires a dedicated client component to configure Amplify for browser-side operations:

// components/ConfigureAmplifyClientSide.tsx
"use client";
import { Amplify } from "aws-amplify";
import outputs from "@/amplify_outputs.json";

Amplify.configure(outputs, { ssr: true });

export default function ConfigureAmplifyClientSide() {
  return null;
}

Import in your root layout:

// app/layout.tsx
import ConfigureAmplifyClientSide from "@/components/ConfigureAmplifyClientSide";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <ConfigureAmplifyClientSide />
        {children}
      </body>
    </html>
  );
}

Why? In App Router, layout.tsx is a server component. Client components need Amplify.configure() to run in the browser. Without this, you get "Auth UserPool not configured" errors.

Vue — src/main.js:

import { Amplify } from 'aws-amplify';
import outputs from '../amplify_outputs.json';
Amplify.configure(outputs);

Angular — src/main.ts:

import { Amplify } from 'aws-amplify';
import outputs from '../amplify_outputs.json';
Amplify.configure(outputs);

Next.js Pages Router

Pages Router does NOT need { ssr: true } in _app.tsx. Instead, configure per-file where you need server-side access:

// pages/api/protected.ts or getServerSideProps
import { Amplify } from 'aws-amplify';
import outputs from '@/amplify_outputs.json';
Amplify.configure(outputs, { ssr: true });

Key difference: App Router uses a global client component. Pages Router configures per-file.

<Authenticator.Provider> is required in layout.tsx for auth context.

React Native

React Native uses the same aws-amplify JS package as web frameworks (it is part of amplify-js, not the native mobile SDKs). All web APIs apply to RN with the additions below.

Required Packages

npm install aws-amplify @aws-amplify/react-native \
  @react-native-async-storage/async-storage \
  react-native-get-random-values

@react-native-async-storage/async-storage is required — the Amplify SDK uses it for token persistence and will fail at runtime without it.

Configure Entry Points

No plugin registration needed — configure only.

React Native (Expo) — App.tsx:

import 'react-native-get-random-values';  // MUST be first
import { Amplify } from 'aws-amplify';
import outputs from './amplify_outputs.json';
Amplify.configure(outputs);

React Native (Bare CLI) — index.js (before AppRegistry.registerComponent):

import 'react-native-get-random-values';  // MUST be first
import { Amplify } from 'aws-amplify';
import outputs from './amplify_outputs.json';
Amplify.configure(outputs);

React Native Pitfalls

• Import order: react-native-get-random-values must be the FIRST import in the entry file, before aws-amplify. Reversing the order causes cryptographic failures at runtime.
• Missing AsyncStorage: Without @react-native-async-storage/async-storage, auth tokens are not persisted and users must re-authenticate on every app restart.

SvelteKit

Configure Amplify in the client hooks file:

// src/hooks.client.ts
import { Amplify } from 'aws-amplify';
import outputs from '../amplify_outputs.json';

Amplify.configure(outputs);

Note: No @aws-amplify/ui-* components exist for Svelte. Use core APIs directly.

Unsupported Frameworks (Astro, Solid, etc.)

For frameworks without official Amplify support:

1. Use npm create amplify@latest -y to scaffold the backend (works in any project)
2. Configure Amplify inside a client-side component (not at build time)

Astro

Amplify is client-side only in Astro. Create a React component (no Astro syntax):

// src/components/AuthenticatedApp.tsx
import { Amplify } from 'aws-amplify';
import { Authenticator } from '@aws-amplify/ui-react';
import outputs from '../amplify_outputs.json';

Amplify.configure(outputs);

export default function AuthenticatedApp() {
  return (
    <Authenticator>
      {({ signOut, user }) => <main>Hello {user?.username}</main>}
    </Authenticator>
  );
}

Use in an Astro page with client:only:

---
// src/pages/index.astro — no Amplify imports here
---
<html>
  <body>
    <AuthenticatedApp client:only="react" />
  </body>
</html>

Must use client:only="react" (NOT client:load) to avoid SSR hydration errors.

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
• How Amplify Works
• CLI Commands
• React Quickstart
• Next.js Quickstart
• Angular Quickstart
• Vue Quickstart
• React Native Quickstart