@thunder-so/thunder 1.3.0 → 1.3.2

package/docs/fargate-full.md

@@ -0,0 +1,177 @@
+# ECS Fargate Configuration Reference
+
+Complete reference for every option available in the `Fargate` construct. Covers container configuration, compute sizing, Nixpacks, secrets, custom domains, and VPC integration. For a quick start see [fargate-basic.md](./fargate-basic.md).
+
+## Full Example
+
+```typescript
+import { Cdk, Fargate, type FargateProps } from '@thunder-so/thunder';
+
+const config: FargateProps = {
+  // Identity
+  env: {
+    account: '123456789012',
+    region: 'us-east-1',
+  },
+  application: 'myapp',
+  service: 'api',
+  environment: 'prod',
+
+  // Source
+  rootDir: '.',   // monorepo: e.g. 'apps/api'
+
+  // Custom Domain
+  domain: 'api.example.com',
+  regionalCertificateArn: 'arn:aws:acm:us-east-1:123456789012:certificate/abc-123',
+  hostedZoneId: 'Z1234567890ABC',
+
+  // Service
+  serviceProps: {
+    dockerFile: 'Dockerfile',
+    dockerBuildArgs: ['NODE_ENV=production'],
+    architecture: Cdk.aws_ecs.CpuArchitecture.ARM64,
+    cpu: 512,
+    memorySize: 1024,
+    port: 3000,
+    desiredCount: 2,
+    healthCheckPath: '/health',
+    variables: [
+      { NODE_ENV: 'production' },
+    ],
+    secrets: [
+      { key: 'DATABASE_URL', resource: 'arn:aws:secretsmanager:us-east-1:123456789012:secret:/myapp/db-abc123' },
+    ],
+  },
+
+  // Build System (Nixpacks alternative to Dockerfile)
+  // buildProps: {
+  //   buildSystem: 'Nixpacks',
+  //   runtime_version: '22',
+  //   installcmd: 'pnpm install',
+  //   buildcmd: 'pnpm run build',
+  //   startcmd: 'pnpm start',
+  // },
+
+  // VPC (optional)
+  // vpc: existingVpc,
+
+  // Debug
+  debug: false,
+};
+
+new Fargate(new Cdk.App(), 'myapp-api-prod-stack', config);
+```
+
+## Property Reference
+
+### Identity (`AppProps`)
+
+| Property | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `env.account` | `string` | Yes | - | AWS account ID |
+| `env.region` | `string` | Yes | - | AWS region |
+| `application` | `string` | Yes | - | Project name |
+| `service` | `string` | Yes | - | Service name |
+| `environment` | `string` | Yes | - | Environment label |
+| `rootDir` | `string` | No | `.` | Root of your app. Used as Docker build context. |
+| `debug` | `boolean` | No | `false` | Enable verbose logging |
+
+### Custom Domain
+
+| Property | Type | Description |
+|---|---|---|
+| `domain` | `string` | Public domain, e.g. `api.example.com` |
+| `regionalCertificateArn` | `string` | ACM certificate ARN - **must be in the same region as the service** |
+| `hostedZoneId` | `string` | Route53 hosted zone ID |
+
+When all three are provided: HTTPS listener is added, HTTP redirects to HTTPS, and a Route53 A record is created.
+
+### `serviceProps`
+
+#### Container
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `dockerFile` | `string` | `Dockerfile` | Path to Dockerfile relative to `rootDir` |
+| `dockerBuildArgs` | `string[]` | - | Build args in `KEY=VALUE` format |
+| `architecture` | `CpuArchitecture` | `X86_64` | `ARM64` or `X86_64`. ARM64 is cheaper on Fargate. |
+| `port` | `number` | `3000` | Port your container listens on |
+| `healthCheckPath` | `string` | `/` | HTTP path for ALB and ECS health checks |
+
+#### Compute
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `cpu` | `number` | `256` | CPU units (256 = 0.25 vCPU). Must be a [valid Fargate combination](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-cpu-memory-error.html). |
+| `memorySize` | `number` | `512` | Memory in MB. Must be valid for the chosen CPU. |
+| `desiredCount` | `number` | `1` | Number of running task instances |
+
+#### Environment
+
+| Property | Type | Description |
+|---|---|---|
+| `variables` | `Array<{ [key: string]: string }>` | Plain environment variables injected into the container |
+| `secrets` | `{ key: string; resource: string }[]` | Secrets Manager ARNs injected as env vars at container start. Task role is granted read access automatically. |
+
+### `buildProps` (Nixpacks)
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `buildSystem` | `'Nixpacks'` | - | Set to `'Nixpacks'` to auto-generate a Dockerfile. Requires Nixpacks CLI installed. |
+| `runtime_version` | `string \| number` | `24` | Node.js version for Nixpacks (`NIXPACKS_NODE_VERSION`) |
+| `installcmd` | `string` | auto | Override install command |
+| `buildcmd` | `string` | auto | Override build command |
+| `startcmd` | `string` | auto | Override start command |
+| `environment` | `Array<{ [key: string]: string }>` | - | Build-time environment variables |
+| `secrets` | `{ key: string; resource: string }[]` | - | Build-time secrets from Secrets Manager |
+
+### VPC
+
+| Property | Type | Description |
+|---|---|---|
+| `vpc` | `IVpc \| IVpcLink` | Attach to an existing VPC. If not provided, a new VPC with 2 public subnets across 2 AZs is created automatically. |
+
+## Networking Details
+
+- Tasks run in **public subnets** with `assignPublicIp: true` (no NAT Gateway cost)
+- A dedicated security group restricts inbound traffic to the ALB only
+- The ALB security group allows all outbound traffic
+- Health check: `wget` to `localhost:PORT/healthCheckPath`, 15s interval, 5s timeout, 3 retries, 60s grace period
+
+## Load Balancer Details
+
+- HTTP/1.1 and HTTP/2 supported
+- HTTP (port 80) is always created; HTTPS (port 443) is added when a domain is configured
+- HTTP → HTTPS redirect is automatic when HTTPS is enabled
+- ALB name is derived from `application-service-environment`
+
+## Stack Outputs
+
+| Output | Description |
+|---|---|
+| `LoadBalancerDNS` | ALB DNS name |
+| `Route53Domain` | Custom domain URL (only if domain is configured) |
+
+## CPU / Memory Valid Combinations
+
+| CPU | vCPU | Valid Memory Values (MB) |
+|---|---|---|
+| 256 | 0.25 | 512, 1024, 2048 |
+| 512 | 0.5 | 1024, 2048, 3072, 4096 |
+| 1024 | 1 | 2048–8192 (in 1024 increments) |
+| 2048 | 2 | 4096–16384 (in 1024 increments) |
+| 4096 | 4 | 8192–30720 (in 1024 increments) |
+
+## Estimated Cost
+
+| Scenario | Monthly (no free tier, `us-east-1`) |
+|---|---|
+| 1 task (0.25 vCPU / 512 MB) | ~$33 |
+| 2 tasks (0.5 vCPU / 1 GB each) | ~$47 |
+
+The ALB (~$22/month) is the dominant fixed cost. See [Fargate pricing](https://aws.amazon.com/fargate/pricing/).
+
+## Related
+
+- [fargate-basic.md](./fargate-basic.md) - Quick start with Dockerfile
+- [fargate-nixpacks.md](./fargate-nixpacks.md) - Auto-generate Dockerfiles with Nixpacks

package/docs/fargate-nixpacks.md

@@ -0,0 +1,199 @@
+# Auto-generate Dockerfiles for Fargate with Nixpacks
+
+Skip writing a `Dockerfile` entirely. [Nixpacks](https://nixpacks.com/) inspects your project, detects the language and framework, and generates an optimized container image automatically. Thunder runs Nixpacks during `cdk synth` and uses the result as your Fargate container.
+
+Works with Node.js, Python, Go, Ruby, Rust, PHP, Java, Deno, and more.
+
+## How It Works
+
+When `buildProps.buildSystem` is set to `'Nixpacks'`, Thunder runs the Nixpacks CLI during `cdk synth` to generate a `.nixpacks/Dockerfile` in your project root. That generated Dockerfile is then used as the container image for your Fargate task.
+
+The flow:
+1. `cdk deploy` triggers synth
+2. Thunder runs `nixpacks build --out .` in your `rootDir`
+3. Nixpacks detects your runtime (Node, Python, Go, etc.) and generates `.nixpacks/Dockerfile`
+4. CDK builds and pushes the image to ECR using that Dockerfile
+5. Fargate pulls and runs the image
+
+## Prerequisites
+
+Install the [Nixpacks CLI](https://nixpacks.com/docs/install):
+
+```bash
+# macOS / Linux
+curl -sSL https://nixpacks.com/install.sh | bash
+
+# or via npm
+npm install -g nixpacks
+```
+
+Verify:
+```bash
+nixpacks --version
+```
+
+## Basic Example
+
+```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: 'prod',
+  rootDir: '.',
+
+  serviceProps: {
+    port: 3000,
+    cpu: 512,
+    memorySize: 1024,
+    desiredCount: 1,
+  },
+
+  buildProps: {
+    buildSystem: 'Nixpacks',
+  },
+};
+
+new Fargate(new Cdk.App(), 'myapp-api-prod-stack', config);
+```
+
+## Custom Commands
+
+Override Nixpacks' auto-detected commands:
+
+```typescript
+buildProps: {
+  buildSystem: 'Nixpacks',
+  installcmd: 'pnpm install',
+  buildcmd: 'pnpm run build',
+  startcmd: 'pnpm start',
+},
+```
+
+If not set, Nixpacks auto-detects the best commands for your project based on `package.json`, `Pipfile`, `go.mod`, etc.
+
+## Node.js Version
+
+Control the Node.js version via `runtime_version`:
+
+```typescript
+buildProps: {
+  buildSystem: 'Nixpacks',
+  runtime_version: '22',  // sets NIXPACKS_NODE_VERSION
+},
+```
+
+## Build Environment Variables
+
+Pass environment variables into the Nixpacks build:
+
+```typescript
+buildProps: {
+  buildSystem: 'Nixpacks',
+  environment: [
+    { VITE_API_URL: 'https://api.example.com' },
+  ],
+},
+```
+
+## Build Secrets
+
+Inject secrets from AWS Secrets Manager into the build environment:
+
+```typescript
+buildProps: {
+  buildSystem: 'Nixpacks',
+  secrets: [
+    { key: 'NPM_TOKEN', resource: 'arn:aws:secretsmanager:us-east-1:123456789012:secret:/myapp/NPM_TOKEN-abc123' },
+  ],
+},
+```
+
+## Full Example with Domain
+
+```typescript
+import { Cdk, Fargate, type FargateProps } from '@thunder-so/thunder';
+
+const config: FargateProps = {
+  env: { account: '123456789012', region: 'us-east-1' },
+  application: 'myapp',
+  service: 'web',
+  environment: 'prod',
+  rootDir: '.',
+
+  domain: 'app.example.com',
+  regionalCertificateArn: 'arn:aws:acm:us-east-1:123456789012:certificate/abc-123',
+  hostedZoneId: 'Z1234567890ABC',
+
+  serviceProps: {
+    architecture: Cdk.aws_ecs.CpuArchitecture.ARM64,
+    cpu: 512,
+    memorySize: 1024,
+    port: 3000,
+    desiredCount: 2,
+    healthCheckPath: '/health',
+    variables: [{ NODE_ENV: 'production' }],
+    secrets: [
+      { key: 'DATABASE_URL', resource: 'arn:aws:secretsmanager:us-east-1:123456789012:secret:/myapp/db-abc123' },
+    ],
+  },
+
+  buildProps: {
+    buildSystem: 'Nixpacks',
+    runtime_version: '22',
+    startcmd: 'node dist/server.js',
+  },
+};
+
+new Fargate(new Cdk.App(), 'myapp-web-prod-stack', config);
+```
+
+## Supported Languages & Frameworks
+
+Nixpacks auto-detects and supports:
+
+- **Node.js** - npm, pnpm, yarn, bun
+- **Python** - pip, pipenv, poetry
+- **Go**
+- **Ruby** - bundler
+- **Rust** - cargo
+- **PHP** - composer
+- **Java** - maven, gradle
+- **Deno**
+
+See the full list in the [Nixpacks documentation](https://nixpacks.com/docs/providers).
+
+## Nixpacks Configuration File
+
+For advanced control, add a `nixpacks.toml` to your project root:
+
+```toml
+# nixpacks.toml
+[phases.install]
+cmds = ["pnpm install --frozen-lockfile"]
+
+[phases.build]
+cmds = ["pnpm run build"]
+
+[start]
+cmd = "node dist/server.js"
+```
+
+See [Nixpacks configuration docs](https://nixpacks.com/docs/configuration/file).
+
+## Troubleshooting
+
+**`nixpacks: command not found`** - Install the CLI before running `cdk deploy`. Thunder calls it during synth.
+
+**Wrong Node version** - Set `runtime_version` in `buildProps` or add a `.node-version` / `.nvmrc` file to your project root.
+
+**Build fails** - Run `nixpacks build .` locally first to debug. The generated Dockerfile is at `.nixpacks/Dockerfile`.
+
+**Port mismatch** - Ensure `serviceProps.port` matches the port your app listens on. Nixpacks sets `PORT` as an env var; use `process.env.PORT` in your app.
+
+## Related
+
+- [fargate-basic.md](./fargate-basic.md) - Basic Dockerfile-based deployment
+- [fargate-full.md](./fargate-full.md) - Full configuration reference

package/docs/frameworks/analogjs-fargate.md

@@ -0,0 +1,115 @@
+# Deploy AnalogJS to AWS Fargate
+
+Run your AnalogJS app with full SSR support on [AWS ECS Fargate](https://aws.amazon.com/fargate/) using Thunder's `Fargate` construct.
+
+## 1. Create a New AnalogJS Project
+
+```bash
+bunx create-analog@latest my-analog-app
+cd my-analog-app
+```
+
+Reference: [AnalogJS Getting Started](https://analogjs.org/docs/getting-started)
+
+## 2. Create Dockerfile
+
+```dockerfile
+FROM oven/bun:latest AS builder
+WORKDIR /app
+
+COPY package.json bun.lockb ./
+RUN bun install --frozen-lockfile
+
+COPY . .
+RUN bun run build
+
+FROM oven/bun:latest AS runner
+WORKDIR /app
+
+ENV NODE_ENV=production
+ENV HOST=0.0.0.0
+ENV PORT=3000
+
+COPY --from=builder /app/dist/analog ./
+
+EXPOSE 3000
+
+CMD ["bun", "run", "server/index.mjs"]
+```
+
+## 3. Install Thunder
+
+```bash
+bun add @thunder-so/thunder --development
+```
+
+## 4. Create Stack File
+
+Create `stack/prod.ts`:
+
+```typescript
+import { Cdk, Fargate, type FargateProps } from '@thunder-so/thunder';
+
+const config: FargateProps = {
+  env: {
+    account: '123456789012',
+    region: 'us-east-1',
+  },
+  application: 'myapp',
+  service: 'web',
+  environment: 'prod',
+  rootDir: '.',
+
+  serviceProps: {
+    dockerFile: 'Dockerfile',
+    architecture: Cdk.aws_ecs.CpuArchitecture.ARM64,
+    cpu: 512,
+    memorySize: 1024,
+    port: 3000,
+    desiredCount: 1,
+    healthCheckPath: '/',
+  },
+};
+
+new Fargate(
+  new Cdk.App(),
+  `${config.application}-${config.service}-${config.environment}-stack`,
+  config
+);
+```
+
+## 5. Deploy
+
+```bash
+npx cdk deploy --app "npx tsx stack/prod.ts" --profile default
+```
+
+## Custom Domain with HTTPS
+
+```typescript
+const config: FargateProps = {
+  // ...
+  domain: 'app.example.com',
+  regionalCertificateArn: 'arn:aws:acm:us-east-1:123456789012:certificate/abc-123',
+  hostedZoneId: 'Z1234567890ABC',
+};
+```
+
+## Environment Variables
+
+```typescript
+serviceProps: {
+  // ...
+  variables: [
+    { NODE_ENV: 'production' },
+  ],
+  secrets: [
+    { key: 'DATABASE_URL', resource: 'arn:aws:secretsmanager:us-east-1:123456789012:secret:/myapp/db-abc123' },
+  ],
+},
+```
+
+## Related
+
+- [fargate-basic.md](../fargate-basic.md) - Fargate construct reference
+- [analogjs-serverless.md](./analogjs-serverless.md) - AnalogJS on Lambda

package/docs/frameworks/analogjs-serverless.md

@@ -0,0 +1,121 @@
+# Deploy AnalogJS to AWS Lambda + S3 + CloudFront
+
+Deploy your AnalogJS app with server-side rendering to AWS using Thunder's `AnalogJS` construct. This creates a hybrid architecture: [Lambda](https://aws.amazon.com/lambda/) handles SSR and API routes, [S3](https://aws.amazon.com/s3/) hosts static assets, and [CloudFront](https://aws.amazon.com/cloudfront/) unifies both.
+
+## 1. Create a New AnalogJS Project
+
+```bash
+bunx create-analog@latest my-analog-app
+cd my-analog-app
+```
+
+Reference: [AnalogJS Getting Started](https://analogjs.org/docs/getting-started)
+
+## 2. Configure Nitro for AWS Lambda
+
+AnalogJS uses [Nitro](https://nitro.unjs.io/) for server-side rendering. Set the `aws-lambda` preset in `vite.config.ts`:
+
+```typescript
+import { defineConfig } from 'vite';
+import analog from '@analogjs/platform';
+
+export default defineConfig({
+  plugins: [
+    analog({
+      nitro: {
+        preset: 'aws-lambda',
+      },
+    }),
+  ],
+});
+```
+
+Reference: [Nitro AWS Lambda Preset](https://nitro.build/deploy/providers/aws)
+
+## 3. Build Your App
+
+```bash
+bun run build
+```
+
+This generates:
+- `dist/analog/server/` - Lambda handler
+- `dist/analog/public/` - Static assets for S3
+
+## 4. Install Thunder
+
+```bash
+bun add @thunder-so/thunder --development
+```
+
+## 5. Create Stack File
+
+Create `stack/prod.ts`:
+
+```typescript
+import { Cdk, AnalogJS, type AnalogJSProps } from '@thunder-so/thunder';
+
+const config: AnalogJSProps = {
+  env: {
+    account: '123456789012',
+    region: 'us-east-1',
+  },
+  application: 'myapp',
+  service: 'web',
+  environment: 'prod',
+  rootDir: '.',
+};
+
+new AnalogJS(
+  new Cdk.App(),
+  `${config.application}-${config.service}-${config.environment}-stack`,
+  config
+);
+```
+
+## 6. Deploy
+
+```bash
+npx cdk deploy --app "npx tsx stack/prod.ts" --profile default
+```
+
+## Custom Domain
+
+```typescript
+const config: AnalogJSProps = {
+  // ...
+  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',
+};
+```
+
+## Environment Variables
+
+```typescript
+serverProps: {
+  variables: [
+    { NODE_ENV: 'production' },
+  ],
+  secrets: [
+    { key: 'DATABASE_URL', resource: 'arn:aws:secretsmanager:us-east-1:123456789012:secret:/myapp/db-abc123' },
+  ],
+},
+```
+
+## Performance Tuning
+
+```typescript
+serverProps: {
+  memorySize: 1792,
+  timeout: 10,
+  keepWarm: true,
+  tracing: true,
+},
+```
+
+## Related
+
+- [serverless.md](../serverless.md) - Serverless construct overview
+- [lambda-basic.md](../lambda-basic.md) - Lambda construct reference