/aws-amplify

Deployment

Prerequisites: Backend defined in amplify/backend.ts with defineBackend({ auth, data }).

Prerequisites

Before deploying, verify:

• npx ampx --version returns a valid version
• aws sts get-caller-identity succeeds
• Node.js ≥ 18.x installed
• .gitignore includes node_modules/, .env*, amplify_outputs.json, .amplify/

amplify_outputs.json is gitignored — it is generated at build time, NOT committed to source control:

• Local dev: npx ampx sandbox generates it automatically
• CI/CD: npx ampx pipeline-deploy generates it during the build phase
• Other frontend apps in a monorepo: Use npx ampx generate outputs --app-id <backend-app-id> to generate it
• Project is a Gen2 project (Gen2 uses amplify/backend.ts + defineBackend())

Sandbox Deployment

Deploy a personal development environment:

AWS_REGION=us-east-1 npx ampx sandbox --once

Use the --once flag in agent and CI environments — without it, the command starts a file watcher that never exits. If prompted to bootstrap, run npx ampx sandbox --once again after bootstrapping completes.

Verify amplify_outputs.json was generated in the project root.

CI/CD Setup

Create the Amplify App

REPO="github.com/<user>/<repo>"
APP_ID=$(aws amplify create-app \
  --name my-app \
  --repository "$REPO" \
  --access-token "$(gh auth token)" \
  --query 'app.appId' --output text)

Use github.com/user/repo format — not https://.

IAM Service Role

Create a dedicated role for Amplify backend deployments:

ROLE_NAME="AmplifyBackendRole-${APP_ID}"

# 1. Create the role with Amplify trust policy
aws iam create-role --role-name "$ROLE_NAME" --assume-role-policy-document '{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": {"Service": "amplify.amazonaws.com"},
    "Action": "sts:AssumeRole"
  }]
}'

# 2. Attach the backend deploy policy
aws iam attach-role-policy --role-name "$ROLE_NAME" \
  --policy-arn arn:aws:iam::aws:policy/service-role/AmplifyBackendDeployFullAccess

# 3. Attach the role to the app
ROLE_ARN=$(aws iam get-role --role-name "$ROLE_NAME" --query 'Role.Arn' --output text)
aws amplify update-app --app-id "$APP_ID" --iam-service-role-arn "$ROLE_ARN"

All three steps are required — missing the role causes AccessDeniedException during deployment.

Create Branch

aws amplify create-branch --app-id "$APP_ID" --branch-name main

amplify.yml

Create amplify.yml in the project root. Set baseDirectory per framework:

Wrong baseDirectory = blank page in production (silent failure). Always match the framework table above.

version: 1
backend:
  phases:
    build:
      commands:
        - npm ci --cache .npm --prefer-offline
        - npx ampx pipeline-deploy --branch $AWS_BRANCH --app-id $AWS_APP_ID
frontend:
  phases:
    build:
      commands:
        - npm ci
        - npm run build
  artifacts:
    baseDirectory: dist # Change per framework (see table above)
    files:
      - '**/*'
  cache:
    paths:
      - .npm/**/*
      - node_modules/**/*

Note: $AWS_BRANCH and $AWS_APP_ID are automatically set by Amplify Hosting. For custom CI/CD pipelines (GitHub Actions, CodePipeline), set these manually or use your pipeline's equivalent variables.

Monorepo Configuration

For monorepos, set appRoot in amplify.yml to the subdirectory containing the Amplify app:

appRoot: packages/web

WARNING: appRoot must have NO leading slash. appRoot: packages/web (correct) vs appRoot: /packages/web (wrong)

Monorepo rules:

• Only ONE app runs npx ampx pipeline-deploy; other apps use npx ampx generate outputs --app-id <backend-app-id> to get their amplify_outputs.json.
• Run npm ci at the repo root, NOT inside appRoot.

Trigger Deployment

aws amplify start-job --app-id "$APP_ID" --branch-name main --job-type RELEASE

Secrets Management

Sandbox: Set secrets via CLI:

echo -n "<value>" | npx ampx sandbox secret set MY_API_KEY

Security: Avoid passing secret values as CLI arguments or via echo — these appear in shell history and /proc. Instead, use npx ampx sandbox secret set MY_SECRET which prompts for input interactively, or pipe from a secure source: aws ssm get-parameter --name /path/to/secret --with-decryption --query Parameter.Value --output text | npx ampx sandbox secret set MY_SECRET --from-stdin

Pipe the value via stdin — without the pipe, the command prompts interactively.

Important: Use echo -n (no trailing newline) when piping values to secret set. (The documented approach uses an interactive prompt; piping with echo -n is a practical alternative for scripts.)

This stores the secret for your personal sandbox environment. Branch environments (production): Secrets are managed through the Amplify console (App settings → Environment variables → Secrets), NOT via CLI. The ampx sandbox secret command only works for local sandbox environments.

Alternatively, use the AWS CLI for non-secret environment variables:

aws amplify update-app --app-id "$APP_ID" \
  --environment-variables MY_API_KEY=<value>

Important: --environment-variables stores values as plain text. For sensitive values (API keys, tokens), use npx ampx sandbox secret set (sandbox) or npx ampx secret set --branch (production) which stores in SSM SecureString.

Note: Under the hood, Amplify Gen2 secret() references are backed by AWS Systems Manager Parameter Store (SecureString parameters). Review access policies on the /amplify/ parameter path in your account to ensure only authorized roles can read production secrets.

Reference secrets in functions using secret() — see functions-and-api.md for the pattern.

Multi-Environment

Use branch-based environments — each Git branch deploys independently:

# Create a staging branch
git checkout -b staging
git push origin staging
aws amplify create-branch --app-id "$APP_ID" --branch-name staging
aws amplify start-job --app-id "$APP_ID" --branch-name staging --job-type RELEASE

Each branch gets isolated backend resources (Cognito pool, AppSync API, DynamoDB tables). Set branch-specific secrets separately.

Custom Domains

Associate a custom domain with the Amplify app:

aws amplify create-domain-association \
  --app-id "$APP_ID" \
  --domain-name example.com \
  --sub-domain-settings '[
    {"prefix": "", "branchName": "main"},
    {"prefix": "staging", "branchName": "staging"}
  ]'

Amplify auto-provisions an SSL certificate. Add the provided CNAME records to your DNS for verification. Check status:

aws amplify get-domain-association --app-id "$APP_ID" --domain-name example.com

Amplify Hosting

Amplify Hosting provides framework-aware builds with SSR support for Next.js. The build pipeline auto-detects the framework from package.json. For SSR apps, Amplify deploys a Lambda@Edge or CloudFront function — no manual CloudFront configuration needed.

Production URL format: https://<branch>.<app-id>.amplifyapp.com

Deployment Validation

After deployment, check job status with aws amplify list-jobs --app-id "$APP_ID" --branch-name main --query 'jobSummaries[0].status' and verify amplify_outputs.json endpoints match expected values.

Post-Deployment

Rollback: Revert via Git and redeploy:

git revert HEAD --no-edit
git push origin main
# Amplify auto-triggers a new build from the push

For CI/CD, manually trigger: aws amplify start-job --app-id "$APP_ID" --branch-name main --job-type RELEASE.

InvalidCredentialError: Failed to load default AWS region

Despite the error name, this is a missing region, not a credential issue:

export AWS_REGION=us-east-1

AppSync API Limit (25 per account)

Each sandbox creates an AppSync API. Frequent sandbox creation/deletion can leave orphaned APIs. If deployment fails with "LimitExceededException":

1. Check: AWS Console → AppSync → APIs → delete unused
2. Request limit increase via Service Quotas

Links

• Fullstack Branching
• Secrets and Variables
• Mono and Multi-Repos
• Custom Pipelines
• Sandbox Environments
• Sandbox Setup