How thunder-so/cdk-spa works
Project Type and Purpose
• This is an open-source AWS CDK library and CLI tool (@thunderso/cdk-spa) for deploying client-side SPAs or SSG sites to AWS S3/CloudFront with optional CI/CD.
• It provides a CLI (bin/app.ts, cli/*.mjs) to scaffold and manage a CDK App, a set of CDK constructs in lib/, CloudFormation stacks in stack/, and optional GitHub Actions or AWS CodePipeline support.
File Structure → Architecture Mapping
• bin/app.ts: CLI entrypoint (Node/TypeScript)
• cli/*.mjs: actual commands (init, deploy, destroy) that bootstrap or orchestrate the CDK App.
• lib/*.ts: core construct definitions (hosting, pipeline, events, deploy logic).
• stack/SPAStack.ts & SPAProps.ts: user-consumable stack API, where you configure domains, redirects, headers, pipeline settings.
• templates/spa.ts: boilerplate CloudFormation template for initial scaffold.
• package.json & workflows: define scripts, dependencies (aws-cdk, tsx), and GitHub Actions config for publishing to NPM.
Main Components
a. Developer Environment & Source Code
• Developer machine (Node.js, AWS CLI, CDK CLI)
• Local Code Repository (bin/, cli/, lib/, stack/, templates/)
b. CLI Layer
• cdk-spa-init → generates stack/index.ts from templates/spa.ts
• cdk-spa-deploy/destroy → invokes npx cdk deploy or destroy
c. CDK App & CloudFormation
• CDK App (bin/app.ts + lib/ + stack/) → synth → CloudFormation templates
• CloudFormation Service → creates/updates AWS resources
d. AWS Infrastructure
• S3 Bucket (static site hosting)
• CloudFront Distribution (edge cache)
• ACM Certificate (us-east-1)
• Route53 Hosted Zone & DNS Records
• Lambda@Edge Functions (redirects, rewrites, headers)
• Optional CodeBuild / CodePipeline (build & deploy pipeline)
e. CI/CD (two flavors)
• GitHub Actions Workflow (.github/workflows/deploy.yml) → checkout → build → cdk deploy
• AWS CodePipeline with CodeBuild
• Source: GitHub (via Personal Access Token in Secrets Manager)
• Build: CodeBuild project (buildspec or buildProps)
• Deploy: CDK CloudFormation
Component Interactions & Data Flows
• Developer runs npx cdk-spa-init → scaffolds stack code
• Developer edits stack/index.ts → configures SPAProps
• Developer (or GitHub Actions) runs npx cdk deploy → CDK CLI → AWS CloudFormation → provisions AWS Services
• Application build artifacts (from outputDir) uploaded to S3 → CloudFront distribution picks them up
• Lambda@Edge functions attached to CloudFront for redirects/rewrites/headers
• Route53 DNS records point domain/subdomain to CloudFront
• In CI/CD mode: GitHub Actions or CodePipeline automatically repeat the above on code pushes
Architectural Patterns & Principles
• Infrastructure as Code (IaC) with AWS CDK and CloudFormation
• Modular CDK Constructs (separate hosting, pipeline, events logic in lib/)
• CLI-Driven Developer Experience (init/deploy/destroy commands)
• Optional Pipelines: declarative (GitHub Actions) or managed (CodePipeline/CodeBuild)
• Edge-Computing: Lambda@Edge for URL handling and HTTP header customizations