# AWS Amplify Documentation

AWS Amplify Documentation is the official documentation site for AWS Amplify, a comprehensive set of tools and services that enable frontend web and mobile developers to build full-stack applications on AWS. The documentation covers Amplify's core features including Authentication, Data/API, Storage, Functions, and more across multiple platforms (React, Next.js, Angular, Vue, React Native, Flutter, Android, Swift, and JavaScript).

This repository is a Next.js-based documentation platform that uses MDX for content authoring, with a sophisticated component system for platform-specific content filtering, code block switching, and interactive UI elements. The site supports two major versions: Gen 2 (current/latest) at the root path and Gen 1 (legacy) under `/gen1/`. Content is organized by platform using dynamic routes (`[platform]`) and features reusable fragments for shared content across platforms.

## Creating Documentation Pages

Every documentation page requires specific metadata and exports for proper rendering and navigation. Pages use MDX format with required meta fields for title, description, and supported platforms.

```mdx
import { getCustomStaticPath } from '@/utils/getCustomStaticPath';

export const meta = {
  title: 'Set up Amplify Auth',
  description:
    'Learn how to set up and connect your backend resources for authentication in Amplify.',
  platforms: [
    'android',
    'angular',
    'flutter',
    'javascript',
    'nextjs',
    'react',
    'react-native',
    'swift',
    'vue'
  ]
};

export function getStaticPaths() {
  return getCustomStaticPath(meta.platforms);
}

export function getStaticProps() {
  return {
    props: {
      meta
    }
  };
}

Amplify Auth is powered by [Amazon Cognito](https://aws.amazon.com/cognito/).

## Getting Started

To get started with defining your authentication resource:

```ts title="amplify/auth/resource.ts"
import { defineAuth } from "@aws-amplify/backend"

export const auth = defineAuth({
  loginWith: {
    email: true,
  },
})
```
```

## InlineFilter Component

The InlineFilter component conditionally renders content based on the user's selected platform. Use this for platform-specific instructions, code examples, or feature availability notes within a single page.

```mdx
<InlineFilter filters={["javascript", "react", "nextjs", "angular", "vue"]}>

## JavaScript-specific Setup

Install the Amplify libraries:

```bash
npm install aws-amplify
```

Configure Amplify in your application:

```javascript
import { Amplify } from 'aws-amplify';
import outputs from './amplify_outputs.json';

Amplify.configure(outputs);
```

</InlineFilter>

<InlineFilter filters={["android"]}>

## Android-specific Setup

Add the Amplify dependencies to your `build.gradle`:

```kotlin
dependencies {
    implementation("com.amplifyframework:core:ANDROID_VERSION")
    implementation("com.amplifyframework:aws-auth-cognito:ANDROID_VERSION")
}
```

</InlineFilter>

<InlineFilter filters={["swift"]}>

## iOS-specific Setup

Add Amplify to your Package.swift:

```swift
dependencies: [
    .package(url: "https://github.com/aws-amplify/amplify-swift", from: "2.0.0")
]
```

</InlineFilter>
```

## BlockSwitcher Component

The BlockSwitcher component creates tabbed code blocks for showing multiple implementations (different languages, frameworks, or approaches) in a compact, switchable interface.

````mdx
<BlockSwitcher>

<Block name="JavaScript">

```javascript
import { signIn } from 'aws-amplify/auth';

async function handleSignIn({ username, password }) {
  try {
    const { isSignedIn, nextStep } = await signIn({ username, password });
    console.log('Sign in successful:', isSignedIn);
  } catch (error) {
    console.log('Error signing in:', error);
  }
}
```

</Block>

<Block name="TypeScript">

```typescript
import { signIn, SignInInput, SignInOutput } from 'aws-amplify/auth';

async function handleSignIn({ username, password }: SignInInput): Promise<SignInOutput> {
  try {
    const result = await signIn({ username, password });
    console.log('Sign in successful:', result.isSignedIn);
    return result;
  } catch (error) {
    console.log('Error signing in:', error);
    throw error;
  }
}
```

</Block>

<Block name="Kotlin">

```kotlin
suspend fun signIn(username: String, password: String) {
    try {
        val result = Amplify.Auth.signIn(username, password)
        if (result.isSignedIn) {
            Log.i("AuthQuickstart", "Sign in succeeded")
        }
    } catch (error: AuthException) {
        Log.e("AuthQuickstart", "Sign in failed", error)
    }
}
```

</Block>

</BlockSwitcher>
````

## Accordion Component

The Accordion component hides supplementary content until the reader expands it. Use for additional context, troubleshooting tips, advanced configurations, or optional deep-dives.

```mdx
<Accordion title='Understanding token refresh' headingLevel='4' eyebrow='Learn more'>

Access tokens are short-lived credentials that expire after a configured period (default: 1 hour). Amplify Auth automatically handles token refresh using refresh tokens when you make authenticated API calls.

The refresh flow works as follows:
1. When an access token expires, Amplify intercepts the 401 response
2. Uses the refresh token to obtain new access and ID tokens
3. Retries the original request with the new tokens
4. If the refresh token is also expired, the user must sign in again

You can customize token expiration in your auth resource:

```typescript
export const auth = defineAuth({
  loginWith: { email: true },
  // Access tokens expire in 30 minutes
  accessTokenValidity: Duration.minutes(30),
  // Refresh tokens expire in 30 days
  refreshTokenValidity: Duration.days(30),
});
```

</Accordion>

<Accordion title='Troubleshooting sign-in errors' headingLevel='4' eyebrow='Troubleshooting'>

**UserNotFoundException**: The username does not exist in the user pool. Verify the user has completed registration.

**NotAuthorizedException**: Incorrect password or the user is not confirmed. Check credentials and user status.

**UserNotConfirmedException**: The user has not verified their account. Prompt them to check their email for a verification code.

```javascript
import { confirmSignUp } from 'aws-amplify/auth';

// After user enters verification code
await confirmSignUp({
  username: 'user@example.com',
  confirmationCode: '123456'
});
```

</Accordion>
```

## Callout Component

The Callout component highlights important information, warnings, or notes. Use the `info` variant for general notes and `warning` for critical warnings.

```mdx
<Callout info>

**Note:** At a minimum you will need to pass a `loginWith` value to set up how your users sign in to your app. Signing in with email and password is configured by default if you do not provide any value.

</Callout>

<Callout warning>

**Security Warning:** Never expose your AWS credentials in client-side code. Always use Amplify's authentication flow which handles credential management securely through Amazon Cognito.

</Callout>

## Example with code block

<Callout info>

You can configure multiple authentication methods:

```typescript
export const auth = defineAuth({
  loginWith: {
    email: true,
    phone: true,
    externalProviders: {
      google: {
        clientId: 'your-google-client-id',
        clientSecret: 'your-google-client-secret'
      }
    }
  }
});
```

</Callout>
```

## Fragments Component

The Fragments component imports and conditionally renders platform-specific content from separate MDX files. Use when content varies significantly between platforms and would be unwieldy as inline filters.

```mdx
import jsAuth from '/src/fragments/lib/auth/js/getting-started.mdx';
import androidAuth from '/src/fragments/lib/auth/android/getting-started.mdx';
import iosAuth from '/src/fragments/lib/auth/ios/getting-started.mdx';
import flutterAuth from '/src/fragments/lib/auth/flutter/getting-started.mdx';

<Fragments
  fragments={{
    javascript: jsAuth,
    angular: jsAuth,
    nextjs: jsAuth,
    react: jsAuth,
    vue: jsAuth,
    android: androidAuth,
    swift: iosAuth,
    flutter: flutterAuth
  }}
/>
```

## Video Component

The Video component embeds MP4 videos with accessibility support and respects user motion preferences. Videos are stored in the `/public` directory.

```mdx
<Video
  src="/videos/auth-flow-demo.mp4"
  description="Video demonstrating the complete authentication flow with email sign-up, verification, and sign-in"
/>

## Multiple videos with context

### Sign Up Flow

<Video
  src="/videos/signup-demo.mp4"
  description="Video showing user registration with email verification"
/>

### Sign In Flow

<Video
  src="/videos/signin-demo.mp4"
  description="Video showing user sign-in with MFA challenge"
/>
```

## YoutubeEmbed Component

The YoutubeEmbed component safely embeds YouTube videos using privacy-enhanced mode (youtube-nocookie.com). Supports custom dimensions and video start times.

```mdx
## Watch the Tutorial

<YoutubeEmbed embedId="dQw4w9WgXcQ" />

## With Custom Dimensions

<YoutubeEmbed
  embedId="dQw4w9WgXcQ"
  width="800"
  height="450"
/>

## Starting at Specific Time

<YoutubeEmbed embedId="dQw4w9WgXcQ?start=120" />
```

## Columns Component

The Columns component creates responsive grid layouts for organizing content side-by-side. Supports 2, 3, or 4 column configurations with small or medium sizing.

```mdx
<Columns columns={2}>

**Authentication Features**
- Email/password sign-in
- Social providers (Google, Facebook, Apple)
- Multi-factor authentication
- Passwordless authentication

**Data Features**
- Real-time subscriptions
- Offline support
- Conflict resolution
- Authorization rules

</Columns>

<Columns columns={3} size="small">

**Auth**
Secure user authentication and authorization

**Data**
Scalable GraphQL and REST APIs

**Storage**
Secure file storage with S3

</Columns>
```

## Overview Component

The Overview component automatically generates a grid of card links to child pages based on the current page's position in the navigation hierarchy.

```mdx
import { getChildPageNodes } from '@/utils/getChildPageNodes';

export function getStaticProps() {
  return {
    props: {
      meta,
      childPageNodes: getChildPageNodes('/[platform]/build-a-backend/auth')
    }
  };
}

## Authentication

Amplify Auth provides a complete authentication solution. Choose a topic below to get started:

<Overview childPageNodes={props.childPageNodes} />
```

## Code Blocks with Highlighting

MDX code blocks support syntax highlighting, titles, line numbers, and line highlighting. Use standard markdown fenced code blocks with language identifiers.

````mdx
## Basic Code Block

```javascript
const greeting = 'Hello, Amplify!';
console.log(greeting);
```

## Code Block with Title

```typescript title="amplify/auth/resource.ts"
import { defineAuth } from '@aws-amplify/backend';

export const auth = defineAuth({
  loginWith: {
    email: true
  }
});
```

## Hide Line Numbers

```bash title="Terminal" showLineNumbers={false}
npx ampx sandbox
```

## Line Highlighting

```typescript
import { signIn } from 'aws-amplify/auth';

// highlight-start
async function handleSignIn(username: string, password: string) {
  const result = await signIn({ username, password });
  return result;
}
// highlight-end

// highlight-next-line
export { handleSignIn };
```

## Version Placeholders

Code blocks automatically replace version placeholders:

```kotlin
dependencies {
    implementation("com.amplifyframework:core:ANDROID_VERSION")
    implementation("com.amplifyframework:aws-auth-cognito:ANDROID_VERSION")
}
```
````

## Internal and External Links

Use standard markdown links for internal navigation (automatically handled by MDXLink) and the ExternalLink component for external resources.

```mdx
## Internal Links

Learn more about [authentication concepts](/[platform]/build-a-backend/auth/concepts/).

See the [MFA setup guide](/[platform]/build-a-backend/auth/concepts/multi-factor-authentication/) for details.

## External Links with Component

<ExternalLink href="https://aws.amazon.com/cognito/">
  Amazon Cognito Documentation
</ExternalLink>

## External Link Button

<ExternalLinkButton href="https://github.com/aws-amplify/amplify-js">
  View on GitHub
</ExternalLinkButton>

## Internal Link Button

<InternalLinkButton href="/[platform]/start/quickstart/">
  Get Started
</InternalLinkButton>
```

## Directory Configuration

Pages must be registered in the directory structure (`src/directory/directory.mjs`) to appear in navigation. The directory defines the hierarchical structure of the documentation.

```javascript
// src/directory/directory.mjs
export const directory = {
  path: 'src/pages/index.tsx',
  children: [
    {
      path: 'src/pages/[platform]/index.tsx',
      children: [
        {
          path: 'src/pages/[platform]/build-a-backend/index.mdx',
          section: 'backend',
          children: [
            {
              path: 'src/pages/[platform]/build-a-backend/auth/index.mdx',
              section: 'backend',
              children: [
                {
                  path: 'src/pages/[platform]/build-a-backend/auth/set-up-auth/index.mdx',
                  section: 'backend'
                },
                {
                  path: 'src/pages/[platform]/build-a-backend/auth/concepts/index.mdx',
                  section: 'backend',
                  children: [
                    { path: 'src/pages/[platform]/build-a-backend/auth/concepts/usernames/index.mdx' },
                    { path: 'src/pages/[platform]/build-a-backend/auth/concepts/email/index.mdx' },
                    { path: 'src/pages/[platform]/build-a-backend/auth/concepts/phone/index.mdx' }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
};
```

## Development Setup

Set up the documentation site locally for development and testing changes.

```bash
# Prerequisites: Node.js 20+ (below 22.0.0)

# Clone the repository
git clone https://github.com/aws-amplify/docs.git
cd docs

# Enable corepack and set yarn version
corepack enable && yarn set version berry

# Install dependencies and start dev server
yarn && yarn dev

# Site opens automatically at http://localhost:3000/

# Run tests
yarn test:unit

# Build for production
yarn build

# Run spellcheck on MDX files
yarn spellcheck
```

## Summary

AWS Amplify Documentation provides comprehensive guides for building full-stack applications with authentication, APIs, storage, and serverless functions across web and mobile platforms. The primary use case is helping developers implement AWS-powered features in their React, Next.js, Angular, Vue, React Native, Flutter, Android, and iOS applications through step-by-step tutorials and API references.

The documentation platform integrates tightly with the Amplify ecosystem, using custom MDX components for platform-specific content filtering, interactive code examples, and consistent styling through AWS Amplify UI. Contributors can author content using familiar markdown syntax enhanced with React components, while the Next.js framework handles static generation, routing, and optimization for the production documentation site at docs.amplify.aws.