/aws-spa-deploy

name: aws-spa-deploy
description: 'Use this skill whenever the user is deploying a React/Vite single-page app to AWS, or mentions Amplify, CDK, or wiring up Lambda + API Gateway for a frontend. Covers Amplify hosting, custom domains, CDK backend (Lambda + API Gateway), SES email, CORS configuration, and environment variables. Skip for non-AWS hosts (Vercel, Netlify, Cloudflare Pages), pure backend services without an SPA, or server-rendered apps (Next.js SSR on Vercel).'

Deploying a Static SPA on AWS

> Applies to: React/Vite SPAs on AWS (Amplify + CDK) | Updated: February 2026

A focused guide for deploying a React/Vite single-page app on AWS with optional API backend using CDK (Cloud Development Kit). Covers Amplify hosting, Lambda + API Gateway, and SES email.

Contents

1. [Before you start](#before-you-start) 2. [Architecture](#architecture) 3. [Costs at a glance](#costs-at-a-glance) 4. [Amplify Hosting](#amplify-hosting) 5. [CDK Backend](#cdk-backend) 6. [SES Email](#ses-email) 7. [Common problems](#common-problems)

---

Before you start

Answer these questions before generating any code. Each has a default assumption - confirm or override before proceeding.

**Q: Do you need a backend API, or is this a static site with no server logic?** Default: static only - if yes, skip the entire CDK section.

**Q: Do you have a custom domain name you want to use?** Default: no - skip the domain and SSL subsections.

**Q: What is your target AWS region, and does it match your default AWS CLI region?** Default: us-east-1. Check with `aws configure get region`. If they differ, pass `--region` explicitly to every CLI command and use the explicit bootstrap form (see CDK section).

**Q: Do you need to send emails from the site (contact forms, notifications)?** Default: no - skip the SES section entirely.

**Q: Is this a brand new AWS account?** Default: no (existing account). If new: SES starts in sandbox mode (can only send to verified addresses), and CDK bootstrap is required before any deploy.

**Q: What is the expected traffic?** Default: low (a few visitors per day) - free tier covers this entirely. See cost table below.

> **AI assistant:** If the user only needs static hosting, generate only the Amplify Hosting section. Only include CDK/Lambda/SES content if they confirm they need a backend.

---

Architecture

Static Site (Amplify = S3 + CloudFront)
    |
    +--> API Gateway (HTTP API) --> Lambda --> SES / DynamoDB / etc.
         OR
    +--> Lambda Function URL --> Lambda --> SES / DynamoDB / etc.

• Static site hosted on **Amplify** (auto-deploys on git push, CDN via CloudFront)
• Backend in a separate **CDK stack** deployed independently
• `VITE_*` environment variables bridge frontend to backend (baked into the JS bundle at build time, not available at runtime)

**This guide uses Amplify Gen 1 (console-based) for static hosting only.** If the Amplify console shows a code-first Gen 2 setup (with an `amplify/` directory in the repo), the hosting and SPA rewrite rules still apply the same way, but the backend configuration sections differ from what is described here.

---

Costs at a glance

| Service | Free tier | What triggers billing | |---|---|---| | Amplify Hosting | 1,000 build minutes/month, 5 GB storage, 15 GB served | Exceeding any of those limits | | Lambda | 1M requests/month, 400,000 GB-seconds compute | High request volume or large memory × long duration | | API Gateway (HTTP API) | 1M requests/month for 12 months | After 12 months or >1M/month | | Lambda Function URL | Same as Lambda - no API Gateway charge | High Lambda invocations | | SES | 62,000 emails/month when sending from EC2/Lambda | Dedicated IPs, high volume beyond free tier | | ACM SSL cert | Free | Never (ACM certs are always free) |

For a typical low-traffic SPA (contact form, a few hundred visitors/month), the effective monthly cost is $0.

---

Amplify Hosting

1. Create an Amplify app in the console and connect your git repo. 2. Amplify auto-detects Vite and sets the build command to `npm run build` with output directory `dist`. Verify this in the build settings. 3. Add a **SPA rewrite rule** under App settings > Rewrites and redirects:

• Source: `/<*>` → Target: `/index.html` → Type: `404-200`
• The type must be `404-200` (not 301 or 302). A redirect would cause the browser to navigate to `/index.html` on every deep link, breaking the URL. A rewrite silently serves `index.html` while keeping the original URL.

4. If you want `www` to redirect to apex: add `https://www.yourdomain.com` → `https://yourdomain.com` with type `301`.

Custom Domain and SSL

Add your domain under App settings > Domain management. Amplify provisions an SSL certificate via ACM (AWS Certificate Manager) automatically.

**ACM cert region gotcha:** The certificate is always provisioned in `us-east-1` regardless of your Amplify app's region. CloudFront requires certificates in `us-east-1`. If you check ACM in any other region you will see nothing - check `us-east-1` specifically.

Add the CNAME records that Amplify provides to your DNS registrar. Propagation typically takes a few minutes but can take up to 48 hours.

Environment Variables

Vite env vars must be prefixed with `VITE_`. They are baked into the JS bundle at build time - they are not accessible at runtime and must not contain secrets.

Set them in Amplify Console > Environment variables, or via CLI:

aws amplify update-app \
  --app-id YOUR_APP_ID \
  --environment-variables VITE_API_URL=https://your-api-url.amazonaws.com \
  --region your-region

After changing env vars, trigger a new build - existing deployments are not updated automatically.

Build Cache

Without an `amplify.yml` cache configuration, `node_modules` is rebuilt from scratch on every deploy, adding 2 - 4 minutes per build. Add this file to your repo root to cache dependencies:

# amplify.yml
version: 1
frontend:
  phase