@thunder-so/thunder 1.3.1 → 1.3.2

package/.kiro/settings/lsp.json

@@ -0,0 +1,198 @@
+{
+  "languages": {
+    "python": {
+      "name": "pyright",
+      "command": "pyright-langserver",
+      "args": [
+        "--stdio"
+      ],
+      "file_extensions": [
+        "py"
+      ],
+      "project_patterns": [
+        "pyproject.toml",
+        "setup.py",
+        "requirements.txt",
+        "pyrightconfig.json"
+      ],
+      "exclude_patterns": [
+        "**/__pycache__/**",
+        "**/venv/**",
+        "**/.venv/**",
+        "**/.pytest_cache/**"
+      ],
+      "multi_workspace": false,
+      "initialization_options": {},
+      "request_timeout_secs": 60
+    },
+    "ruby": {
+      "name": "solargraph",
+      "command": "solargraph",
+      "args": [
+        "stdio"
+      ],
+      "file_extensions": [
+        "rb"
+      ],
+      "project_patterns": [
+        "Gemfile",
+        "Rakefile"
+      ],
+      "exclude_patterns": [
+        "**/vendor/**",
+        "**/tmp/**"
+      ],
+      "multi_workspace": false,
+      "initialization_options": {},
+      "request_timeout_secs": 60
+    },
+    "cpp": {
+      "name": "clangd",
+      "command": "clangd",
+      "args": [
+        "--background-index"
+      ],
+      "file_extensions": [
+        "cpp",
+        "cc",
+        "cxx",
+        "c",
+        "h",
+        "hpp",
+        "hxx"
+      ],
+      "project_patterns": [
+        "CMakeLists.txt",
+        "compile_commands.json",
+        "Makefile"
+      ],
+      "exclude_patterns": [
+        "**/build/**",
+        "**/cmake-build-**/**"
+      ],
+      "multi_workspace": false,
+      "initialization_options": {},
+      "request_timeout_secs": 60
+    },
+    "typescript": {
+      "name": "typescript-language-server",
+      "command": "typescript-language-server",
+      "args": [
+        "--stdio"
+      ],
+      "file_extensions": [
+        "ts",
+        "js",
+        "tsx",
+        "jsx"
+      ],
+      "project_patterns": [
+        "package.json",
+        "tsconfig.json"
+      ],
+      "exclude_patterns": [
+        "**/node_modules/**",
+        "**/dist/**"
+      ],
+      "multi_workspace": false,
+      "initialization_options": {
+        "preferences": {
+          "disableSuggestions": false
+        }
+      },
+      "request_timeout_secs": 60
+    },
+    "java": {
+      "name": "jdtls",
+      "command": "jdtls",
+      "args": [],
+      "file_extensions": [
+        "java"
+      ],
+      "project_patterns": [
+        "pom.xml",
+        "build.gradle",
+        "build.gradle.kts",
+        ".project"
+      ],
+      "exclude_patterns": [
+        "**/target/**",
+        "**/build/**",
+        "**/.gradle/**"
+      ],
+      "multi_workspace": false,
+      "initialization_options": {
+        "settings": {
+          "java": {
+            "compile": {
+              "nullAnalysis": {
+                "mode": "automatic"
+              }
+            },
+            "configuration": {
+              "annotationProcessing": {
+                "enabled": true
+              }
+            }
+          }
+        }
+      },
+      "request_timeout_secs": 60
+    },
+    "rust": {
+      "name": "rust-analyzer",
+      "command": "rust-analyzer",
+      "args": [],
+      "file_extensions": [
+        "rs"
+      ],
+      "project_patterns": [
+        "Cargo.toml"
+      ],
+      "exclude_patterns": [
+        "**/target/**"
+      ],
+      "multi_workspace": false,
+      "initialization_options": {
+        "cargo": {
+          "buildScripts": {
+            "enable": true
+          }
+        },
+        "diagnostics": {
+          "enable": true,
+          "enableExperimental": true
+        },
+        "workspace": {
+          "symbol": {
+            "search": {
+              "scope": "workspace"
+            }
+          }
+        }
+      },
+      "request_timeout_secs": 60
+    },
+    "go": {
+      "name": "gopls",
+      "command": "gopls",
+      "args": [],
+      "file_extensions": [
+        "go"
+      ],
+      "project_patterns": [
+        "go.mod",
+        "go.sum"
+      ],
+      "exclude_patterns": [
+        "**/vendor/**"
+      ],
+      "multi_workspace": false,
+      "initialization_options": {
+        "usePlaceholders": true,
+        "completeUnimported": true
+      },
+      "request_timeout_secs": 60
+    }
+  }
+}

package/README.md

@@ -7,7 +7,7 @@
 
 Build full-stack apps on your own AWS.
 
-Thunder is a CDK library and CLI for deploying modern web applications on AWS. One library to rule them all: [Static SPAs](#static), [Lambda Functions](#lambda), [Containers on Fargate](#fargate) and [EC2](#ec2), and [Full-stack Frameworks](#full-stack-frameworks).
+Thunder is a CDK library and CLI for deploying modern web applications on AWS. One library to rule them all: [Static SPAs](#static), [Lambda Functions](#lambda), [Containers on Fargate](#fargate) and [EC2](#ec2), and [Serverless Full-stack Frameworks](#serverless-frameworks).
 
 ## Table of Contents
 
@@ -19,8 +19,7 @@ Thunder is a CDK library and CLI for deploying modern web applications on AWS. O
   - [Lambda](#lambda) - API Gateway + Lambda
   - [Fargate](#fargate) - ECS Fargate + ALB + CloudFront
   - [EC2](#ec2) - EC2 + Docker + Elastic IP
-  - [Nuxt](#nuxt) - Serverless full-stack with Lambda
-  - [Astro](#astro) - Serverless full-stack SSR with Lambda
+  - [Serverless Frameworks](#serverless-frameworks) - Full-stack meta-frameworks with Lambda + S3 + CloudFront
   - [Template](#template) - Coolify-style templates
 - [CLI Commands](#cli-commands)
 - [Documentation](#documentation)
@@ -28,7 +27,7 @@ Thunder is a CDK library and CLI for deploying modern web applications on AWS. O
 
 ## Features
 
-- **Constructs:** One-line deployment for `Static`, `Lambda`, `Fargate`, `EC2`, `Nuxt`, and `Astro`.
+- **Constructs:** One-line deployment for `Static`, `Lambda`, `Fargate`, `EC2`, `Serverless`, and framework-specific constructs.
 - **Thunder CLI (`th`):** Context-aware CLI for initializing, deploying, and managing your infrastructure.
 - **VPC Link Pattern:** Easily connect your compute resources to a shared VPC.
 - **High-Performance Serving:** Pre-configured [CloudFront](https://aws.amazon.com/cloudfront/) distributions with OAC, security headers, and edge optimizations.
@@ -39,7 +38,7 @@ Thunder is a CDK library and CLI for deploying modern web applications on AWS. O
 - **Static:** Vite (React, Vue, Svelte, Solid), Next.js (SSG), Astro (SSG), Gatsby.
 - **Serverless:** Node.js Lambda, Bun, Container-based Lambda.
 - **Containers:** [ECS Fargate](https://aws.amazon.com/fargate/) with ALB, Docker on [EC2](https://aws.amazon.com/ec2/) with Elastic IP.
-- **Full-stack SSR:** [Nuxt.js](https://nuxt.com/), [Astro](https://astro.build/) (SSR), and extensibility for SvelteKit, TanStack Start, AnalogJS.
+- **Full-stack SSR:** [Nuxt](https://nuxt.com/), [Astro](https://astro.build/), [TanStack Start](https://tanstack.com/start), [SvelteKit](https://kit.svelte.dev/), [Solid Start](https://start.solidjs.com/), [AnalogJS](https://analogjs.org/).
 
 ## Quick Start
 
@@ -267,87 +266,14 @@ new Ec2(new Cdk.App(), 'myapp-api-prod-stack', config);
 
 ---
 
-### Full-Stack Frameworks
-
-#### Nuxt
-
-Deploy [Nuxt.js](https://nuxt.com/) SSR applications with hybrid rendering - Lambda for server-side and S3 for static assets.
-
-**Best for:** Vue-based full-stack applications with server-side rendering
-
-**AWS Resources:**
-- [Lambda Function](https://aws.amazon.com/lambda/) - SSR server
-- [S3 Bucket](https://aws.amazon.com/s3/) - Static assets
-- [CloudFront Distribution](https://aws.amazon.com/cloudfront/) - Unified CDN
-- [API Gateway](https://aws.amazon.com/api-gateway/) - HTTP API
-
-**Example:**
-```typescript
-import { Cdk, Nuxt, type NuxtProps } from '@thunder-so/thunder';
-
-const config: NuxtProps = {
-  env: { account: '123456789012', region: 'us-east-1' },
-  application: 'myapp',
-  service: 'web',
-  environment: 'prod',
-  rootDir: '.',
-  
-  serverProps: {
-    runtime: Cdk.aws_lambda.Runtime.NODEJS_22_X,
-    architecture: Cdk.aws_lambda.Architecture.ARM_64,
-    memorySize: 1792,
-    timeout: 10,
-    keepWarm: true,
-  },
-  
-  // Optional: Custom domain
-  domain: 'example.com',
-  globalCertificateArn: 'arn:aws:acm:us-east-1:...',
-  hostedZoneId: 'Z123456789',
-};
-
-new Nuxt(new Cdk.App(), 'myapp-web-prod-stack', config);
-```
-
----
-
-#### Astro
-
-Deploy [Astro](https://astro.build/) SSR applications with the same infrastructure pattern as Nuxt.
-
-**Best for:** Content-focused websites with server-side rendering and islands architecture
-
-**AWS Resources:** Same as [Nuxt](#nuxt)
-
-**Example:**
-```typescript
-import { Cdk, Astro, type NuxtProps as AstroProps } from '@thunder-so/thunder';
-
-const config: AstroProps = {
-  env: { account: '123456789012', region: 'us-east-1' },
-  application: 'myapp',
-  service: 'web',
-  environment: 'prod',
-  rootDir: '.',
-  
-  serverProps: {
-    runtime: Cdk.aws_lambda.Runtime.NODEJS_22_X,
-    architecture: Cdk.aws_lambda.Architecture.ARM_64,
-    memorySize: 1024,
-  },
-};
-
-new Astro(new Cdk.App(), 'myapp-web-prod-stack', config);
-```
-
----
-
 ### Serverless Frameworks
 
 Deploy modern meta-frameworks as serverless applications with unified infrastructure - Lambda for server-side rendering and S3 for static assets, all behind CloudFront.
 
 **Best for:** Full-stack applications with server-side rendering, API routes, and static asset optimization
 
+**Supported Frameworks:** Nuxt, Astro, TanStack Start, SvelteKit, Solid Start, AnalogJS, or any Vite/Nitro-based framework using the generic `Serverless` construct.
+
 **AWS Resources:**
 - [Lambda Function](https://aws.amazon.com/lambda/) - SSR server with container support
 - [S3 Bucket](https://aws.amazon.com/s3/) - Static assets with OAC
@@ -360,7 +286,6 @@ Deploy modern meta-frameworks as serverless applications with unified infrastruc
 - [TanStack Start](https://tanstack.com/start) - Type-safe full-stack React framework
 - [Nuxt](https://nuxt.com/) - Vue-based full-stack framework
 - [Astro](https://astro.build/) - Content-focused web framework with islands architecture
-- [React Router v7](https://reactrouter.com/) - Full-stack React framework with nested routing
 - [SvelteKit](https://kit.svelte.dev/) - Svelte-based full-stack framework
 - [Solid Start](https://start.solidjs.com/) - SolidJS full-stack framework
 - [AnalogJS](https://analogjs.org/) - Angular-based full-stack framework
@@ -460,43 +385,6 @@ const config: AstroProps = {
 new Astro(new Cdk.App(), 'myapp-web-prod-stack', config);
 ```
 
-#### React Router
-
-Deploy [React Router v7](https://reactrouter.com/) framework mode applications with server-side rendering and API routes.
-
-**Best for:** React applications with nested routing, server-side rendering, and modern React Router patterns
-
-**AWS Resources:** Same as [TanStack Start](#tanstack-start)
-
-**Example:**
-```typescript
-import { Cdk, ReactRouter, type ReactRouterProps } from '@thunder-so/thunder';
-
-const config: ReactRouterProps = {
-  env: { account: '123456789012', region: 'us-east-1' },
-  application: 'myapp',
-  service: 'web',
-  environment: 'prod',
-  rootDir: '.',
-  
-  serverProps: {
-    runtime: Cdk.aws_lambda.Runtime.NODEJS_22_X,
-    architecture: Cdk.aws_lambda.Architecture.ARM_64,
-    memorySize: 1024,
-    timeout: 10,
-    keepWarm: true,
-    variables: [{ NODE_ENV: 'production' }],
-  },
-  
-  // Optional: Custom domain
-  domain: 'myapp.com',
-  globalCertificateArn: 'arn:aws:acm:us-east-1:...',
-  hostedZoneId: 'Z123456789',
-};
-
-new ReactRouter(new Cdk.App(), 'myapp-web-prod-stack', config);
-```
-
 #### SvelteKit
 
 **Example:**
@@ -654,6 +542,60 @@ main();
 
 For detailed documentation on each construct and advanced configurations, see the [Wiki](https://github.com/thunder-so/thunder/wiki).
 
+### Static
+
+| Guide | Description |
+| :--- | :--- |
+| [static-basic.md](./docs/static-basic.md) | Deploy a static site or SPA to S3 + CloudFront |
+| [static-edge-functions.md](./docs/static-edge-functions.md) | Redirects, rewrites, and custom headers via Lambda@Edge |
+| [static-full.md](./docs/static-full.md) | Full `StaticProps` configuration reference |
+
+### Lambda
+
+| Guide | Description |
+| :--- | :--- |
+| [lambda-basic.md](./docs/lambda-basic.md) | Deploy a serverless API with Lambda + API Gateway |
+| [lambda-containers.md](./docs/lambda-containers.md) | Container images and Bun runtime |
+| [lambda-full.md](./docs/lambda-full.md) | Full `LambdaProps` configuration reference |
+
+### Fargate
+
+| Guide | Description |
+| :--- | :--- |
+| [fargate-basic.md](./docs/fargate-basic.md) | Deploy a containerized service on ECS Fargate |
+| [fargate-nixpacks.md](./docs/fargate-nixpacks.md) | Auto-generate Dockerfiles with Nixpacks |
+| [fargate-full.md](./docs/fargate-full.md) | Full `FargateProps` configuration reference |
+
+### Serverless (Full-Stack Frameworks)
+
+| Guide | Description |
+| :--- | :--- |
+| [serverless.md](./docs/serverless.md) | Deploy full-stack meta-frameworks with SSR |
+
+### Framework Guides
+
+**Static Deployment:**
+- [Next.js Static](./docs/frameworks/nextjs-static.md)
+- [Astro Static](./docs/frameworks/astro-static.md)
+
+**Serverless (Lambda + S3 + CloudFront):**
+- [Nuxt](./docs/frameworks/nuxt-serverless.md)
+- [Astro SSR](./docs/frameworks/astro-serverless.md)
+- [TanStack Start](./docs/frameworks/tanstack-start-serverless.md)
+- [SvelteKit](./docs/frameworks/sveltekit-serverless.md)
+- [Solid Start](./docs/frameworks/solidstart-serverless.md)
+- [AnalogJS](./docs/frameworks/analogjs-serverless.md)
+
+**Fargate (Containers):**
+- [Next.js with Dockerfile](./docs/frameworks/nextjs-fargate-dockerfile.md)
+- [Next.js with Nixpacks](./docs/frameworks/nextjs-fargate-nixpacks.md)
+- [Astro](./docs/frameworks/astro-fargate.md)
+- [Nuxt](./docs/frameworks/nuxt-fargate.md)
+- [TanStack Start](./docs/frameworks/tanstack-start-fargate.md)
+- [SvelteKit](./docs/frameworks/sveltekit-fargate.md)
+- [Solid Start](./docs/frameworks/solidstart-fargate.md)
+- [AnalogJS](./docs/frameworks/analogjs-fargate.md)
+
 ## License
 
 Apache-2.0

package/docs/fargate-basic.md

@@ -0,0 +1,222 @@
+# Deploy Containerized Apps to AWS ECS Fargate
+
+Run any Docker container as a production web service on [AWS ECS Fargate](https://aws.amazon.com/fargate/) - serverless containers with an [Application Load Balancer](https://aws.amazon.com/elasticloadbalancing/application-load-balancer/) in front. No EC2 instances, no cluster management, and automatic health checks and restarts.
+
+Works with any language or framework you can containerize: Next.js, Express, NestJS, Django, Rails, Go, Rust, and more.
+
+## AWS Resources
+
+| Resource | Purpose |
+|---|---|
+| [ECS Cluster](https://aws.amazon.com/ecs/) | Container orchestration |
+| [Fargate Task](https://aws.amazon.com/fargate/) | Serverless container runtime |
+| [Application Load Balancer](https://aws.amazon.com/elasticloadbalancing/) | Public HTTP/HTTPS endpoint, health checks |
+| [VPC](https://aws.amazon.com/vpc/) | Network isolation (created automatically if not provided) |
+| [CloudWatch Logs](https://aws.amazon.com/cloudwatch/) | Container logs, retained for 1 week |
+| [ACM Certificate](https://aws.amazon.com/certificate-manager/) | SSL for custom domain (optional) |
+| [Route53](https://aws.amazon.com/route53/) | DNS A record (optional) |
+
+## Prerequisites
+
+- [Docker](https://docs.docker.com/get-docker/) installed and running locally
+- [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) configured
+- [AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html) bootstrapped:
+  ```bash
+  cdk bootstrap aws://YOUR_ACCOUNT_ID/us-east-1
+  ```
+
+## Installation
+
+```bash
+bun add @thunder-so/thunder --development
+# or
+npm install @thunder-so/thunder --save-dev
+```
+
+## Dockerfile
+
+Your app needs a `Dockerfile`. Here's a production-ready example for a Node.js app:
+
+```dockerfile
+# Dockerfile
+
+# Build stage
+FROM public.ecr.aws/docker/library/node:22-alpine AS builder
+WORKDIR /app
+COPY . .
+RUN corepack enable && corepack prepare pnpm@latest --activate
+RUN pnpm install
+RUN pnpm run build
+
+# Production stage
+FROM public.ecr.aws/docker/library/node:22-alpine AS runner
+WORKDIR /app
+ENV NODE_ENV=production
+RUN corepack enable && corepack prepare pnpm@latest --activate
+COPY --from=builder /app/ ./
+EXPOSE 3000
+CMD ["pnpm", "start"]
+```
+
+Add a `.dockerignore` to keep the build context lean:
+
+```
+.git
+node_modules
+cdk.out
+stack
+.DS_Store
+```
+
+## Stack File
+
+```typescript
+import { Cdk, Fargate, type FargateProps } from '@thunder-so/thunder';
+
+const config: FargateProps = {
+  env: {
+    account: '123456789012',
+    region: 'us-east-1',
+  },
+  application: 'myapp',
+  service: 'api',
+  environment: 'dev',
+
+  rootDir: '.',
+
+  serviceProps: {
+    dockerFile: 'Dockerfile',
+    architecture: Cdk.aws_ecs.CpuArchitecture.ARM64,
+    cpu: 256,        // 0.25 vCPU
+    memorySize: 512, // 512 MB
+    port: 3000,
+    desiredCount: 1,
+    healthCheckPath: '/health',
+  },
+};
+
+new Fargate(
+  new Cdk.App(),
+  `${config.application}-${config.service}-${config.environment}-stack`,
+  config
+);
+```
+
+## Deploy
+
+```bash
+npx cdk deploy --app "npx tsx stack/dev.ts" --profile default
+```
+
+CDK builds your Docker image, pushes it to ECR, and deploys the service. The ALB DNS name is output:
+
+```
+Outputs:
+myapp-api-dev-stack.LoadBalancerDNS = myapp-api-dev-1234567890.us-east-1.elb.amazonaws.com
+```
+
+## Custom Domain with HTTPS (Optional)
+
+1. [Create a Route53 Hosted Zone](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/AboutHZWorkingWith.html)
+2. [Request an ACM certificate](https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-request-public.html) in the **same region as your service**
+
+```typescript
+const config: FargateProps = {
+  // ...
+  domain: 'api.example.com',
+  regionalCertificateArn: 'arn:aws:acm:us-east-1:123456789012:certificate/abc-123',
+  hostedZoneId: 'Z1234567890ABC',
+};
+```
+
+When a domain is configured:
+- HTTPS listener is added on port 443
+- HTTP on port 80 redirects to HTTPS
+- Route53 A record is created pointing to the ALB
+
+## Environment Variables
+
+```typescript
+serviceProps: {
+  // ...
+  variables: [
+    { NODE_ENV: 'production' },
+    { PORT: '3000' },
+  ],
+},
+```
+
+## Secrets from AWS Secrets Manager
+
+```bash
+aws secretsmanager create-secret \
+  --name "/myapp/DATABASE_URL" \
+  --secret-string "postgres://user:pass@host/db"
+```
+
+```typescript
+serviceProps: {
+  // ...
+  secrets: [
+    { key: 'DATABASE_URL', resource: 'arn:aws:secretsmanager:us-east-1:123456789012:secret:/myapp/DATABASE_URL-abc123' },
+  ],
+},
+```
+
+Secrets are injected as environment variables at container startup. The task role is automatically granted read access.
+
+## Health Check
+
+The ALB and ECS both perform health checks. By default they hit `/`. Configure a dedicated health endpoint:
+
+```typescript
+serviceProps: {
+  healthCheckPath: '/health',
+},
+```
+
+Your app should return `200 OK` on that path within 5 seconds.
+
+## CPU & Memory Sizing
+
+Fargate uses [fixed CPU/memory combinations](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-cpu-memory-error.html):
+
+| CPU (units) | vCPU | Valid Memory (MB) |
+|---|---|---|
+| 256 | 0.25 | 512, 1024, 2048 |
+| 512 | 0.5 | 1024–4096 |
+| 1024 | 1 | 2048–8192 |
+| 2048 | 2 | 4096–16384 |
+| 4096 | 4 | 8192–30720 |
+
+## Estimated Cost
+
+A minimal deployment (1 task, `us-east-1`, no free tier):
+
+| Component | Monthly |
+|---|---|
+| Fargate (1 task, 0.25 vCPU / 512 MB) | ~$9 |
+| Application Load Balancer | ~$22 |
+| CloudWatch Logs | <$1 |
+| Route53 | $0.50 |
+| **Total** | **~$33/month** |
+
+See [Fargate pricing](https://aws.amazon.com/fargate/pricing/) and [ALB pricing](https://aws.amazon.com/elasticloadbalancing/pricing/).
+
+## Stack Outputs
+
+| Output | Description |
+|---|---|
+| `LoadBalancerDNS` | ALB DNS name |
+| `Route53Domain` | Custom domain URL (only if domain is configured) |
+
+## Destroy
+
+```bash
+npx cdk destroy --app "npx tsx stack/dev.ts" --profile default
+```
+
+## Next Steps
+
+- [fargate-nixpacks.md](./fargate-nixpacks.md) - Auto-generate Dockerfiles with Nixpacks
+- [fargate-full.md](./fargate-full.md) - Full configuration reference