@thunder-so/thunder 1.3.1 → 1.3.2

package/docs/serverless.md

@@ -0,0 +1,267 @@
+# Deploy Full-Stack Meta-Frameworks to AWS Lambda + S3 + CloudFront
+
+Thunder's `Serverless` construct deploys modern full-stack frameworks with server-side rendering (SSR) to AWS using a hybrid architecture: [AWS Lambda](https://aws.amazon.com/lambda/) handles dynamic server requests, [S3](https://aws.amazon.com/s3/) hosts static assets, and [CloudFront](https://aws.amazon.com/cloudfront/) unifies both behind a single domain with intelligent routing.
+
+This pattern works with any meta-framework that uses [Nitro](https://nitro.unjs.io/) or a compatible server runtime: Nuxt, Astro, TanStack Start, SvelteKit, Solid Start, AnalogJS, and more.
+
+## Architecture
+
+```
+User Request
+    ↓
+CloudFront (CDN)
+    ├─→ /assets/* → S3 (static files: JS, CSS, images)
+    ├─→ /api/* → Lambda (API routes)
+    └─→ /* → Lambda (SSR pages)
+```
+
+- **Static assets** (`*.js`, `*.css`, `*.png`, etc.) are cached long-term at CloudFront edge locations
+- **Dynamic requests** (SSR pages, API routes) hit Lambda through API Gateway
+- **Single domain** - no CORS issues, unified caching strategy
+
+## AWS Resources
+
+| Resource | Purpose |
+|---|---|
+| [Lambda Function](https://aws.amazon.com/lambda/) | Runs your server-side code (SSR, API routes) |
+| [API Gateway HTTP API](https://aws.amazon.com/api-gateway/) | Routes dynamic requests to Lambda |
+| [S3 Bucket](https://aws.amazon.com/s3/) | Hosts static assets (JS, CSS, images) |
+| [CloudFront Distribution](https://aws.amazon.com/cloudfront/) | Global CDN with origin routing |
+| [Origin Access Control (OAC)](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-restricting-access-to-s3.html) | Secures S3 - no public bucket access |
+| [ACM Certificate](https://aws.amazon.com/certificate-manager/) | SSL/TLS for custom domain (optional) |
+| [Route53](https://aws.amazon.com/route53/) | DNS A + AAAA records (optional) |
+
+## Supported Frameworks
+
+| Framework | Construct | Server Runtime | Notes |
+|---|---|---|---|
+| [Nuxt](https://nuxt.com/) | `Nuxt` | Nitro | Vue-based, `aws-lambda` preset |
+| [Astro](https://astro.build/) | `Astro` | @astro-aws/adapter | Requires Lambda@Edge fallback |
+| [TanStack Start](https://tanstack.com/start) | `TanStackStart` | Nitro | React-based, explicit `aws-lambda` preset required |
+| [SvelteKit](https://kit.svelte.dev/) | `SvelteKit` | @foladayo/sveltekit-adapter-lambda | Requires `serveStatic: true` |
+| [Solid Start](https://start.solidjs.com/) | `SolidStart` | Nitro | SolidJS-based, `aws-lambda` preset |
+| [AnalogJS](https://analogjs.org/) | `AnalogJS` | Nitro | Angular-based, `aws-lambda` preset |
+
+See [framework-specific guides](#framework-guides) below for setup instructions.
+
+## Prerequisites
+
+- [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
+  ```
+- Your app built with framework-specific build command
+
+## Installation
+
+```bash
+bun add @thunder-so/thunder --development
+# or
+npm install @thunder-so/thunder --save-dev
+```
+
+## Basic Example (Nuxt)
+
+```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: '.',
+};
+
+new Nuxt(new Cdk.App(), 'myapp-web-prod-stack', config);
+```
+
+## Deploy
+
+```bash
+# Build your app first
+bun run build
+
+# Deploy
+npx cdk deploy --app "npx tsx stack/prod.ts" --profile default
+```
+
+CDK outputs the CloudFront URL and API Gateway URL:
+
+```
+Outputs:
+myapp-web-prod-stack.CloudFrontUrl = https://d1234abcd.cloudfront.net
+myapp-web-prod-stack.ApiGatewayUrl = https://abc123.execute-api.us-east-1.amazonaws.com
+```
+
+## Custom Domain (Optional)
+
+1. [Create a Route53 Hosted Zone](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/AboutHZWorkingWith.html)
+2. [Request a global ACM certificate](https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-request-public.html) in **`us-east-1`** (for CloudFront)
+3. [Request a regional ACM certificate](https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-request-public.html) in your **function's region** (for API Gateway)
+
+```typescript
+const config: ServerlessBaseProps = {
+  // ...
+  domain: 'app.example.com',
+  hostedZoneId: 'Z1234567890ABC',
+  globalCertificateArn: 'arn:aws:acm:us-east-1:123456789012:certificate/abc-123',
+  regionalCertificateArn: 'arn:aws:acm:us-east-1:123456789012:certificate/def-456',
+};
+```
+
+> CloudFront requires a certificate in `us-east-1` (global). API Gateway requires a certificate in the same region as your Lambda function.
+
+## Configuration
+
+### Server (Lambda)
+
+```typescript
+serverProps: {
+  memorySize: 1792,
+  timeout: 10,
+  keepWarm: true,
+  tracing: true,
+  variables: [
+    { NODE_ENV: 'production' },
+  ],
+  secrets: [
+    { key: 'DATABASE_URL', resource: 'arn:aws:secretsmanager:us-east-1:123456789012:secret:/myapp/db-abc123' },
+  ],
+},
+```
+
+### CloudFront Cache Behavior
+
+```typescript
+// Cache control
+allowHeaders: ['Accept-Language'],
+allowCookies: ['session-*'],
+allowQueryParams: ['lang'],
+denyQueryParams: ['utm_source', 'fbclid'],  // mutually exclusive with allowQueryParams
+
+// Custom error page
+errorPagePath: '/404.html',
+```
+
+## Container Mode (Docker)
+
+For larger apps or custom runtimes, use Docker:
+
+```typescript
+serverProps: {
+  dockerFile: 'Dockerfile',
+  dockerBuildArgs: { NODE_ENV: 'production' },
+  memorySize: 2048,
+},
+```
+
+Thunder builds and pushes the image to [Amazon ECR](https://aws.amazon.com/ecr/) automatically. See framework-specific docs for Dockerfile examples.
+
+## Environment Variables
+
+```typescript
+serverProps: {
+  variables: [
+    { NODE_ENV: 'production' },
+    { API_BASE_URL: 'https://api.example.com' },
+  ],
+},
+```
+
+## Secrets from AWS Secrets Manager
+
+```bash
+aws secretsmanager create-secret \
+  --name "/myapp/DATABASE_URL" \
+  --secret-string "postgres://user:pass@host/db"
+```
+
+```typescript
+serverProps: {
+  secrets: [
+    { key: 'DATABASE_URL', resource: 'arn:aws:secretsmanager:us-east-1:123456789012:secret:/myapp/DATABASE_URL-abc123' },
+  ],
+},
+```
+
+## Keep Warm
+
+Prevent cold starts by pinging the Lambda every 5 minutes:
+
+```typescript
+serverProps: {
+  keepWarm: true,
+},
+```
+
+## Stack Outputs
+
+| Output | Description |
+|---|---|
+| `CloudFrontUrl` | CloudFront distribution URL |
+| `ApiGatewayUrl` | API Gateway endpoint URL |
+| `Route53Domain` | Custom domain URL (only if domain is configured) |
+
+## Framework Guides
+
+Detailed setup instructions for each framework:
+
+- [Nuxt Serverless](./frameworks/nuxt-serverless.md)
+- [Astro Serverless](./frameworks/astro-serverless.md)
+- [TanStack Start Serverless](./frameworks/tanstack-start-serverless.md)
+- [SvelteKit Serverless](./frameworks/sveltekit-serverless.md)
+- [Solid Start Serverless](./frameworks/solidstart-serverless.md)
+- [AnalogJS Serverless](./frameworks/analogjs-serverless.md)
+
+## Generic Serverless Deployment
+
+For any Vite/Nitro-based meta-framework not explicitly supported, use the generic `Serverless` construct:
+
+```typescript
+import { Cdk, Serverless, type ServerlessProps } from '@thunder-so/thunder';
+
+const config: ServerlessProps = {
+  env: { account: '123456789012', region: 'us-east-1' },
+  application: 'myapp',
+  service: 'web',
+  environment: 'prod',
+  rootDir: '.',
+  
+  serverProps: {
+    codeDir: '.output/server',  // Your framework's server output
+    handler: 'index.handler',
+    runtime: Cdk.aws_lambda.Runtime.NODEJS_22_X,
+    architecture: Cdk.aws_lambda.Architecture.ARM_64,
+    memorySize: 1792,
+    timeout: 10,
+  },
+  
+  clientProps: {
+    outputDir: '.output/public',  // Your framework's static assets
+  },
+};
+
+new Serverless(
+  new Cdk.App(),
+  'myapp-web-prod-stack',
+  { ...config, framework: 'custom' }
+);
+```
+
+This works with any framework that outputs a Lambda-compatible handler and static assets.
+
+
+
+```bash
+npx cdk destroy --app "npx tsx stack/prod.ts" --profile default
+```
+
+> The S3 bucket uses `RemovalPolicy.RETAIN` to prevent accidental data loss. Delete it manually from the AWS console if needed.
+
+## Related
+
+- [lambda-basic.md](./lambda-basic.md) - Lambda construct reference
+- [static-basic.md](./static-basic.md) - Static construct reference
+- [fargate-basic.md](./fargate-basic.md) - Fargate construct reference

package/docs/static-basic.md

@@ -0,0 +1,151 @@
+# Deploy Static Sites and SPAs to AWS S3 + CloudFront
+
+Host your frontend on AWS in minutes. Thunder's `Static` construct deploys your build output to [Amazon S3](https://aws.amazon.com/s3/) and serves it globally through a [CloudFront](https://aws.amazon.com/cloudfront/) CDN - with HTTPS, HTTP/3, Brotli compression, and security headers out of the box.
+
+Works with any framework that produces a static output folder: Vite (React, Vue, Svelte, Solid), Next.js static export, Astro SSG, Gatsby, and more.
+
+## AWS Resources
+
+| Resource | Purpose |
+|---|---|
+| [S3 Bucket](https://aws.amazon.com/s3/) | Stores your build output. Private, accessed only via CloudFront OAC. |
+| [CloudFront Distribution](https://aws.amazon.com/cloudfront/) | Global CDN. HTTP/3, TLS 1.2+, Brotli/Gzip compression. |
+| [Origin Access Control (OAC)](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-restricting-access-to-s3.html) | Secures S3 - no public bucket access. |
+| [ACM Certificate](https://aws.amazon.com/certificate-manager/) | SSL/TLS for your custom domain (optional). |
+| [Route53](https://aws.amazon.com/route53/) | DNS A + AAAA records for IPv4/IPv6 (optional). |
+
+## Prerequisites
+
+- [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) configured with credentials
+- [AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html) bootstrapped in your target account/region:
+  ```bash
+  cdk bootstrap aws://YOUR_ACCOUNT_ID/us-east-1
+  ```
+- Your app's build output directory (e.g. `dist/`)
+
+## Installation
+
+```bash
+bun add @thunder-so/thunder --development
+# or
+npm install @thunder-so/thunder --save-dev
+```
+
+## Stack File
+
+Create `stack/dev.ts` (use separate files per environment):
+
+```typescript
+import { Cdk, Static, type StaticProps } from '@thunder-so/thunder';
+
+const config: StaticProps = {
+  env: {
+    account: '123456789012',
+    region: 'us-east-1',
+  },
+  application: 'myapp',
+  service: 'web',
+  environment: 'dev',
+
+  rootDir: '.',       // monorepo: e.g. 'apps/web'
+  outputDir: 'dist',  // your framework's build output folder
+};
+
+new Static(
+  new Cdk.App(),
+  `${config.application}-${config.service}-${config.environment}-stack`,
+  config
+);
+```
+
+## Deploy
+
+```bash
+npx cdk deploy --app "npx tsx stack/dev.ts" --profile default
+```
+
+After deployment, CDK outputs the CloudFront distribution URL:
+
+```
+Outputs:
+myapp-web-dev-stack.DistributionUrl = https://d1234abcd.cloudfront.net
+```
+
+## Custom Domain (Optional)
+
+To serve from your own domain you need:
+
+1. A [Route53 Hosted Zone](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/AboutHZWorkingWith.html) for your domain
+2. A [public ACM certificate](https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-request-public.html) issued in **`us-east-1`** (required for CloudFront, regardless of your app's region)
+
+```typescript
+const config: StaticProps = {
+  // ...
+  domain: 'app.example.com',
+  globalCertificateArn: 'arn:aws:acm:us-east-1:123456789012:certificate/abc-123',
+  hostedZoneId: 'Z1234567890ABC',
+};
+```
+
+> The certificate **must** be in `us-east-1` because CloudFront is a global service.
+
+## Configuration Reference
+
+### Core
+
+| Property | Type | Required | Description |
+|---|---|---|---|
+| `env.account` | `string` | Yes | AWS account ID |
+| `env.region` | `string` | Yes | AWS region |
+| `application` | `string` | Yes | Project identifier |
+| `service` | `string` | Yes | Service identifier |
+| `environment` | `string` | Yes | Environment name (e.g. `prod`) |
+| `rootDir` | `string` | No | Root of your app. Defaults to `.` |
+| `outputDir` | `string` | No | Build output directory. Defaults to `dist` |
+| `debug` | `boolean` | No | Enables S3 access logs and CloudFront logging |
+
+### Domain
+
+| Property | Type | Description |
+|---|---|---|
+| `domain` | `string` | Custom domain, e.g. `app.example.com` |
+| `globalCertificateArn` | `string` | ACM certificate ARN (must be `us-east-1`) |
+| `hostedZoneId` | `string` | Route53 hosted zone ID |
+
+### CloudFront Behavior
+
+| Property | Type | Description |
+|---|---|---|
+| `errorPagePath` | `string` | Custom 404 page path, e.g. `/404.html`. Defaults to `/index.html` |
+| `allowHeaders` | `string[]` | Headers to include in cache key and forward to origin |
+| `allowCookies` | `string[]` | Cookies to include in cache key |
+| `allowQueryParams` | `string[]` | Query params to include in cache key |
+| `denyQueryParams` | `string[]` | Query params to strip from cache key (e.g. UTM params). Mutually exclusive with `allowQueryParams` |
+
+## Default Security Headers
+
+The distribution ships with a secure-by-default response headers policy:
+
+| Header | Value |
+|---|---|
+| `Strict-Transport-Security` | `max-age=31536000; includeSubDomains; preload` |
+| `X-Frame-Options` | `DENY` |
+| `X-Content-Type-Options` | `nosniff` |
+| `Referrer-Policy` | `strict-origin-when-cross-origin` |
+| `Content-Security-Policy` | `default-src 'self'; style-src https: 'unsafe-inline'; ...` |
+| `X-XSS-Protection` | `1; mode=block` |
+
+To add custom headers per path, see [static-edge-functions.md](./static-edge-functions.md).
+
+## Destroy
+
+```bash
+npx cdk destroy --app "npx tsx stack/dev.ts" --profile default
+```
+
+> The S3 hosting bucket uses `RemovalPolicy.RETAIN` to prevent accidental data loss. Delete it manually from the AWS console if needed.
+
+## Next Steps
+
+- [static-edge-functions.md](./static-edge-functions.md) - Add redirects, rewrites, and custom headers via Lambda@Edge
+- [static-full.md](./static-full.md) - Full configuration reference with all options

package/docs/static-edge-functions.md

@@ -0,0 +1,187 @@
+# CloudFront Redirects, Rewrites, and Custom Headers with Lambda@Edge
+
+Add URL redirects, path rewrites, and custom HTTP response headers to your CloudFront distribution - no origin round-trip required. Thunder deploys [Lambda@Edge](https://aws.amazon.com/lambda/edge/) functions automatically when you configure these options, running your rules at AWS edge locations worldwide.
+
+Two functions are created:
+
+| Function | CloudFront Event | Purpose |
+|---|---|---|
+| `RedirectRewriteFunction` | `viewer-request` | Evaluates redirects and rewrites before the cache |
+| `HeadersFunction` | `viewer-response` | Injects custom headers into responses |
+
+> Lambda@Edge functions are always deployed to `us-east-1` and replicated globally by CloudFront.
+
+## Redirects
+
+A redirect returns an HTTP `301 Moved Permanently` response, causing the browser to navigate to a new URL. Use redirects when a URL has permanently moved.
+
+```typescript
+import { Cdk, Static, type StaticProps } from '@thunder-so/thunder';
+
+const config: StaticProps = {
+  // ...core config...
+
+  redirects: [
+    // Static redirect
+    { source: '/home', destination: '/' },
+
+    // Wildcard - captures everything after /guide/
+    { source: '/guide/*', destination: '/docs/*' },
+
+    // Named placeholders
+    { source: '/blog/:year/:month', destination: '/posts/:year/:month' },
+  ],
+};
+```
+
+### Pattern Syntax
+
+| Pattern | Matches |
+|---|---|
+| `/about` | Exact path `/about` |
+| `/blog/*` | Any path starting with `/blog/` |
+| `/user/:id` | `/user/123`, `/user/abc`, etc. |
+| `/a/:x/b/:y` | `/a/foo/b/bar` → placeholders `x=foo`, `y=bar` |
+
+Wildcards (`*`) and placeholders (`:name`) can be used in both `source` and `destination`. Placeholders are positional - they map by name between source and destination.
+
+## Rewrites
+
+A rewrite changes the path the request is forwarded to internally, without changing the URL in the browser. Use rewrites to serve a different file while keeping the original URL visible.
+
+```typescript
+const config: StaticProps = {
+  // ...
+
+  rewrites: [
+    // Serve index.html for all app routes (SPA fallback)
+    { source: '/app/*', destination: '/index.html' },
+
+    // Map a vanity URL to a real path
+    { source: '/profile/:username', destination: '/user/:username' },
+  ],
+};
+```
+
+### SPA Fallback Pattern
+
+For client-side routed SPAs, rewrite all unmatched paths to `index.html`:
+
+```typescript
+rewrites: [
+  { source: '/*', destination: '/index.html' },
+],
+```
+
+> Rewrites run after redirects. If a path matches a redirect rule, the rewrite is never evaluated.
+
+## Custom HTTP Headers
+
+Use `headers` to inject or override HTTP response headers for specific path patterns. This runs at the `viewer-response` stage, so it applies to both cached and uncached responses.
+
+```typescript
+const config: StaticProps = {
+  // ...
+
+  headers: [
+    // Cache HTML for 10 minutes
+    { path: '/*', name: 'Cache-Control', value: 'public, max-age=600' },
+
+    // Long-lived cache for hashed assets
+    { path: '/assets/*', name: 'Cache-Control', value: 'public, max-age=31536000, immutable' },
+
+    // Restrict embedding to same origin
+    { path: '/**', name: 'X-Frame-Options', value: 'SAMEORIGIN' },
+
+    // CORS for a specific API path
+    { path: '/api/*', name: 'Access-Control-Allow-Origin', value: 'https://app.example.com' },
+  ],
+};
+```
+
+### Path Syntax
+
+| Path | Matches |
+|---|---|
+| `/*` | Root-level paths only |
+| `/**` | All paths including nested |
+| `/blog/*` | All paths under `/blog/` |
+| `/assets/*.{js,css}` | JS and CSS files under `/assets/` |
+
+### Header Evaluation Order
+
+Headers are applied in array order. Later entries for the same header name on the same path will overwrite earlier ones.
+
+> Custom headers defined here are applied **after** the built-in security headers policy. To override a default security header (e.g. `X-Frame-Options`), specify it explicitly here.
+
+## Default Security Headers
+
+These are always applied by the CloudFront Response Headers Policy, regardless of your `headers` config:
+
+| Header | Default |
+|---|---|
+| `Strict-Transport-Security` | `max-age=31536000; includeSubDomains; preload` |
+| `X-Frame-Options` | `DENY` |
+| `X-Content-Type-Options` | `nosniff` |
+| `Referrer-Policy` | `strict-origin-when-cross-origin` |
+| `X-XSS-Protection` | `1; mode=block` |
+| `Content-Security-Policy` | `default-src 'self'; style-src https: 'unsafe-inline'; script-src https: 'unsafe-inline' 'wasm-unsafe-eval'; ...` |
+
+Default CORS headers (applied to all origins):
+
+| Header | Default |
+|---|---|
+| `Access-Control-Allow-Origin` | `*` |
+| `Access-Control-Allow-Methods` | `GET, HEAD, OPTIONS` |
+| `Access-Control-Allow-Headers` | `*` |
+| `Access-Control-Max-Age` | `600` |
+
+## Full Example
+
+```typescript
+import { Cdk, Static, type StaticProps } from '@thunder-so/thunder';
+
+const config: StaticProps = {
+  env: { account: '123456789012', region: 'us-east-1' },
+  application: 'myapp',
+  service: 'web',
+  environment: 'prod',
+  rootDir: '.',
+  outputDir: 'dist',
+
+  domain: 'app.example.com',
+  globalCertificateArn: 'arn:aws:acm:us-east-1:123456789012:certificate/abc-123',
+  hostedZoneId: 'Z1234567890ABC',
+
+  redirects: [
+    { source: '/old-page', destination: '/new-page' },
+  ],
+
+  rewrites: [
+    { source: '/app/*', destination: '/index.html' },
+  ],
+
+  headers: [
+    { path: '/**', name: 'X-Frame-Options', value: 'SAMEORIGIN' },
+    { path: '/assets/*', name: 'Cache-Control', value: 'public, max-age=31536000, immutable' },
+  ],
+};
+
+new Static(new Cdk.App(), 'myapp-web-prod-stack', config);
+```
+
+## Troubleshooting
+
+**Redirects not firing:** Lambda@Edge logs appear in CloudWatch in the region closest to the viewer, not `us-east-1`. Check the relevant regional log group `/aws/lambda/us-east-1.RedirectRewriteFunction`.
+
+**Headers not appearing:** Verify the path pattern matches your URL. Use `/**` to match all paths including nested ones.
+
+**CSP blocking resources:** The default CSP is strict. Override it with a `headers` entry:
+```typescript
+{ path: '/**', name: 'Content-Security-Policy', value: 'your-custom-policy' }
+```
+
+## Related
+
+- [static-basic.md](./static-basic.md) - Basic setup
+- [static-full.md](./static-full.md) - Full configuration reference