aws-spa-deploy

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:
4. Source: /<*> → Target: /index.html → Type: 404-200
5. 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.
6. 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:
  phases:
    preBuild:
      commands:
        - npm ci
    build:
      commands:
        - npm run build
  artifacts:
    baseDirectory: dist
    files:
      - '**/*'
  cache:
    paths:
      - node_modules/**/*

CDK Backend

When to use API Gateway vs Lambda Function URLs

Use API Gateway (HTTP API) when you have multiple routes, need request validation, or plan to add auth (JWT authorizers, IAM). It adds a small latency overhead and a per-request cost after the free tier.

Use Lambda Function URLs when you have a single endpoint (contact form, webhook handler) and do not need routing or auth middleware. They are free beyond Lambda's own cost, have no additional latency layer, and require less CDK code.

Lambda Function URL example (simpler):

const handler = new lambda.Function(this, 'Handler', {
  runtime: lambda.Runtime.NODEJS_22_X,
  handler: 'handler.handler',
  code: lambda.Code.fromAsset('lambda'),
  memorySize: 256,
  timeout: cdk.Duration.seconds(10),
});

const fnUrl = handler.addFunctionUrl({
  authType: lambda.FunctionUrlAuthType.NONE,
  cors: {
    allowedOrigins: ['https://yourdomain.com', 'http://localhost:5173', 'http://localhost:4173'],
    allowedMethods: [lambda.HttpMethod.POST],
    allowedHeaders: ['Content-Type'],
  },
});

new cdk.CfnOutput(this, 'FunctionUrl', { value: fnUrl.url });

Project Structure

infra/
├── bin/app.ts           # CDK app entry
├── lib/api-stack.ts     # Stack definition
├── lambda/handler.mjs   # Lambda handler (ESM, use .mjs extension)
├── cdk.json
├── package.json
└── tsconfig.json

Bootstrap

CDK bootstrap creates the S3 bucket and IAM roles that CDK needs to deploy. Run it once per account/region combination.

# Explicit form  -  use this to avoid deploying to the wrong region
npx cdk bootstrap aws://YOUR_ACCOUNT_ID/your-region

Running npx cdk bootstrap without arguments uses your AWS CLI default region. If your CLI default region differs from the target deployment region, CDK resources land in the wrong region with no error. Always use the explicit aws://ACCOUNT_ID/REGION form.

Minimal Stack (API Gateway + Lambda)

import * as cdk from 'aws-cdk-lib';
import * as lambda from 'aws-cdk-lib/aws-lambda';
import * as apigwv2 from 'aws-cdk-lib/aws-apigatewayv2';
import * as integrations from 'aws-cdk-lib/aws-apigatewayv2-integrations';
import { Construct } from 'constructs';

export class ApiStack extends