---

name: aws-amplify description: Deploys and hosts full-stack web applications on AWS Amplify with SSR support, CI/CD, and backend services. Use when deploying Next.js apps to AWS, setting up Amplify hosting, or configuring Amplify backends.

AWS Amplify Hosting

Full-stack deployment platform for web applications with automatic CI/CD, SSR support, and integrated AWS services.

Quick Start

# Install Amplify CLI
npm install -g @aws-amplify/cli

# Configure AWS credentials
amplify configure

# Initialize Amplify in project
amplify init

# Deploy via Console
# 1. Go to AWS Amplify Console
# 2. Connect your Git repository
# 3. Amplify auto-detects framework

Supported Frameworks

• Next.js (SSR, SSG, ISR)
• React (CRA, Vite)
• Vue.js / Nuxt
• Angular
• Gatsby
• Astro
• SvelteKit
• Static sites

Git-Based Deployment

Connect Repository

1. AWS Console > Amplify > Create new app
2. Choose Git provider (GitHub, GitLab, Bitbucket, CodeCommit)
3. Select repository and branch
4. Review build settings
5. Deploy

amplify.yml (Build Spec)

version: 1
applications:
  - frontend:
      phases:
        preBuild:
          commands:
            - npm ci
        build:
          commands:
            - npm run build
      artifacts:
        baseDirectory: .next
        files:
          - '**/*'
      cache:
        paths:
          - node_modules/**/*
          - .next/cache/**/*

Next.js Configuration

Next.js 14+ (App Router)

version: 1
frontend:
  phases:
    preBuild:
      commands:
        - npm ci
    build:
      commands:
        - npm run build
  artifacts:
    baseDirectory: .next
    files:
      - '**/*'
  cache:
    paths:
      - node_modules/**/*
      - .next/cache/**/*

Environment Variables

version: 1
frontend:
  phases:
    build:
      commands:
        - echo "NEXT_PUBLIC_API_URL=$NEXT_PUBLIC_API_URL" >> .env.production
        - npm run build

Custom Headers

# amplify.yml
customHeaders:
  - pattern: '**/*'
    headers:
      - key: Strict-Transport-Security
        value: max-age=31536000; includeSubDomains
      - key: X-Content-Type-Options
        value: nosniff
      - key: X-Frame-Options
        value: DENY
  - pattern: '*.js'
    headers:
      - key: Cache-Control
        value: public, max-age=31536000, immutable

Environment Variables

Console Setup

1. App settings > Environment variables
2. Add key-value pairs
3. Choose branch scope (all or specific)

In amplify.yml

frontend:
  phases:
    build:
      commands:
        - printenv | grep -E '^(NEXT_|REACT_APP_)' >> .env.production
        - npm run build

Secrets

Store sensitive values securely:

frontend:
  phases:
    preBuild:
      commands:
        - aws secretsmanager get-secret-value --secret-id prod/api-key --query SecretString --output text > .env.local

Custom Domains

Add Domain

1. App settings > Domain management
2. Add domain
3. Configure DNS (Route 53 or external)
4. Wait for SSL certificate

Subdomains

# Branch subdomains
main    -> example.com
develop -> dev.example.com
feature -> feature.example.com

Redirects & Rewrites

amplify.yml

customRules:
  # Redirect
  - source: /old-path
    target: /new-path
    status: '301'

  # Rewrite (proxy)
  - source: /api/<*>
    target: https://api.example.com/<*>
    status: '200'

  # SPA fallback
  - source: </^[^.]+$|\.(?!(css|gif|ico|jpg|js|png|txt|svg|woff|ttf|map|json)$)([^.]+$)/>
    target: /index.html
    status: '200'

Branch Deployments

Auto Branch Detection

# amplify.yml (root)
version: 1
backend:
  phases:
    build:
      commands:
        - amplifyPush --simple
frontend:
  phases:
    build:
      commands:
        - npm run build

Branch-Specific Builds

frontend:
  phases:
    build:
      commands:
        - if [ "$AWS_BRANCH" = "main" ]; then npm run build:prod; else npm run build:dev; fi

Monorepo Setup

Select App Directory

1. During setup, enable "My app is a monorepo"
2. Specify app root: apps/web

amplify.yml

version: 1
applications:
  - appRoot: apps/web
    frontend:
      phases:
        preBuild:
          commands:
            - npm ci
        build:
          commands:
            - npm run build
      artifacts:
        baseDirectory: .next
        files:
          - '**/*'

Build Performance

Caching

cache:
  paths:
    - node_modules/**/*
    - .next/cache/**/*
    - ~/.npm/**/*

Build Image

frontend:
  phases:
    preBuild:
      commands:
        - nvm use 20
        - npm ci

Preview Deployments

Pull Request Previews

1. App settings > Previews
2. Enable previews
3. Configure:
   • Preview branches
   • Access control (password/Cognito)

# Branch patterns
# feature/** -> Preview deployment
# main -> Production

IAM Service Role

Required Permissions

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "amplify:*",
        "s3:*",
        "cloudfront:*",
        "route53:*",
        "acm:*",
        "logs:*"
      ],
      "Resource": "*"
    }
  ]
}

Troubleshooting

Build Fails

frontend:
  phases:
    build:
      commands:
        - npm run build 2>&1 | tee build.log

Memory Issues

frontend:
  phases:
    build:
      commands:
        - NODE_OPTIONS="--max-old-space-size=8192" npm run build

Image Optimization

Next.js image optimization works automatically. Amplify deploys Sharp internally.

See references/configuration.md for complete build spec and references/backends.md for Amplify backend setup.