@thunder-so/thunder 1.3.0 → 1.3.2

package/docs/frameworks/astro-fargate.md

@@ -0,0 +1,120 @@
+# Deploy Astro to AWS Fargate
+
+Run your Astro app with full SSR support on [AWS ECS Fargate](https://aws.amazon.com/fargate/) using Thunder's `Fargate` construct.
+
+## 1. Create a New Astro Project
+
+```bash
+bunx create-astro@latest my-astro-app
+cd my-astro-app
+```
+
+Reference: [Astro Installation Docs](https://docs.astro.build/en/install-and-setup/)
+
+## 2. Configure Astro for Node Server
+
+Edit `astro.config.mjs`:
+
+```javascript
+import { defineConfig } from 'astro/config';
+import node from '@astrojs/node';
+
+export default defineConfig({
+  output: 'server',
+  adapter: node({
+    mode: 'standalone',
+  }),
+});
+```
+
+## 3. Create Dockerfile
+
+```dockerfile
+FROM public.ecr.aws/docker/library/node:22-alpine AS builder
+WORKDIR /app
+
+COPY package.json bun.lockb ./
+RUN corepack enable && corepack prepare bun@latest --activate
+RUN bun install --frozen-lockfile
+
+COPY . .
+RUN bun run build
+
+FROM public.ecr.aws/docker/library/node:22-alpine AS runner
+WORKDIR /app
+
+ENV NODE_ENV=production
+ENV HOST=0.0.0.0
+ENV PORT=4321
+
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/node_modules ./node_modules
+COPY --from=builder /app/package.json ./
+
+EXPOSE 4321
+
+CMD ["node", "./dist/server/entry.mjs"]
+```
+
+## 4. Install Thunder
+
+```bash
+bun add @thunder-so/thunder --development
+```
+
+## 5. 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: 4321,
+    desiredCount: 1,
+    healthCheckPath: '/',
+  },
+};
+
+new Fargate(
+  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: FargateProps = {
+  // ...
+  domain: 'app.example.com',
+  regionalCertificateArn: 'arn:aws:acm:us-east-1:123456789012:certificate/abc-123',
+  hostedZoneId: 'Z1234567890ABC',
+};
+```
+
+## Related
+
+- [fargate-basic.md](../fargate-basic.md) - Fargate construct reference
+- [astro-serverless.md](./astro-serverless.md) - Astro on Lambda

package/docs/frameworks/astro-serverless.md

@@ -0,0 +1,112 @@
+# Deploy Astro with SSR to AWS Lambda + S3 + CloudFront
+
+Deploy your Astro app with server-side rendering to AWS using Thunder's `Astro` 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 Astro Project
+
+```bash
+bunx create-astro@latest my-astro-app
+cd my-astro-app
+```
+
+Reference: [Astro Installation Docs](https://docs.astro.build/en/install-and-setup/)
+
+## 2. Install AWS Adapter
+
+```bash
+bun add @astro-aws/adapter
+```
+
+## 3. Configure Astro for AWS Lambda
+
+Edit `astro.config.mjs`:
+
+```javascript
+import { defineConfig } from 'astro/config';
+import aws from '@astro-aws/adapter';
+
+export default defineConfig({
+  output: 'server',  // Enable SSR
+  adapter: aws(),
+});
+```
+
+Reference: [@astro-aws/adapter](https://www.npmjs.com/package/@astro-aws/adapter)
+
+## 4. Build Your App
+
+```bash
+bun run build
+```
+
+This generates:
+- `dist/lambda/` - Lambda handler
+- `dist/client/` - Static assets for S3
+
+## 5. Install Thunder
+
+```bash
+bun add @thunder-so/thunder --development
+```
+
+## 6. Create Stack File
+
+Create `stack/prod.ts`:
+
+```typescript
+import { Cdk, Astro, type AstroProps } from '@thunder-so/thunder';
+
+const config: AstroProps = {
+  env: {
+    account: '123456789012',
+    region: 'us-east-1',
+  },
+  application: 'myapp',
+  service: 'web',
+  environment: 'prod',
+  rootDir: '.',
+};
+
+new Astro(
+  new Cdk.App(),
+  `${config.application}-${config.service}-${config.environment}-stack`,
+  config
+);
+```
+
+## 7. Deploy
+
+```bash
+npx cdk deploy --app "npx tsx stack/prod.ts" --profile default
+```
+
+## Custom Domain
+
+```typescript
+const config: AstroProps = {
+  // ...
+  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: 'API_KEY', resource: 'arn:aws:secretsmanager:us-east-1:123456789012:secret:/myapp/api-abc123' },
+  ],
+},
+```
+
+## Related
+
+- [serverless.md](../serverless.md) - Serverless construct overview
+- [astro-static.md](./astro-static.md) - Astro static site
+- [astro-fargate.md](./astro-fargate.md) - Astro on Fargate

package/docs/frameworks/astro-static.md

@@ -0,0 +1,108 @@
+# Deploy Astro Static Site to AWS S3 + CloudFront
+
+Host your Astro site as a static site on AWS using Thunder's `Static` construct. This guide covers static site generation (SSG) mode - HTML, CSS, and JavaScript served from [S3](https://aws.amazon.com/s3/) through [CloudFront](https://aws.amazon.com/cloudfront/).
+
+## 1. Create a New Astro Project
+
+```bash
+bunx create-astro@latest my-astro-site
+cd my-astro-site
+```
+
+When prompted:
+- Template: Choose any (e.g., "Empty", "Blog", "Portfolio")
+- TypeScript: Yes (recommended)
+- Install dependencies: Yes
+- Git repository: Yes (optional)
+
+Reference: [Astro Installation Docs](https://docs.astro.build/en/install-and-setup/)
+
+## 2. Configure Static Output
+
+Edit `astro.config.mjs`:
+
+```javascript
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+  output: 'static',  // Default, but explicit is better
+});
+```
+
+Reference: [Astro Static Exports](https://docs.astro.build/en/guides/deploy/)
+
+## 3. Build Your App
+
+```bash
+bun run build
+```
+
+This generates static files in the `dist/` directory.
+
+## 4. Install Thunder
+
+```bash
+bun add @thunder-so/thunder --development
+```
+
+## 5. Create Stack File
+
+Create `stack/prod.ts`:
+
+```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',
+};
+
+new Static(
+  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: StaticProps = {
+  // ...
+  domain: 'site.example.com',
+  globalCertificateArn: 'arn:aws:acm:us-east-1:123456789012:certificate/abc-123',
+  hostedZoneId: 'Z1234567890ABC',
+};
+```
+
+## Redirects and Rewrites
+
+```typescript
+const config: StaticProps = {
+  // ...
+  redirects: [
+    { source: '/old-page', destination: '/new-page' },
+  ],
+  rewrites: [
+    { source: '/blog/*', destination: '/posts/*' },
+  ],
+};
+```
+
+## Related
+
+- [static-basic.md](../static-basic.md) - Static construct reference
+- [astro-serverless.md](./astro-serverless.md) - Astro with SSR on Lambda

package/docs/frameworks/nextjs-fargate-dockerfile.md

@@ -0,0 +1,227 @@
+# Deploy Next.js to AWS Fargate with Dockerfile
+
+Run your Next.js app with full SSR support on [AWS ECS Fargate](https://aws.amazon.com/fargate/) using Thunder's `Fargate` construct. This deploys your app as a Docker container with an [Application Load Balancer](https://aws.amazon.com/elasticloadbalancing/application-load-balancer/) in front - no EC2 instances to manage.
+
+Perfect for Next.js apps that need server-side rendering, API routes, or features not supported by static export.
+
+## 1. Create a New Next.js Project
+
+```bash
+bunx create-next-app@latest my-nextjs-app
+cd my-nextjs-app
+```
+
+When prompted:
+- TypeScript: Yes
+- ESLint: Yes
+- Tailwind CSS: Yes (optional)
+- `src/` directory: No (optional)
+- App Router: Yes
+- Turbopack: Yes (optional)
+
+Reference: [Next.js Installation Docs](https://nextjs.org/docs/getting-started/installation)
+
+## 2. Configure Next.js for Standalone Output
+
+Edit `next.config.ts`:
+
+```typescript
+import type { NextConfig } from 'next';
+
+const nextConfig: NextConfig = {
+  output: 'standalone',  // Optimized for Docker
+};
+
+export default nextConfig;
+```
+
+Reference: [Next.js Standalone Output](https://nextjs.org/docs/app/api-reference/next-config-js/output)
+
+## 3. Create Dockerfile
+
+Create `Dockerfile` in your project root:
+
+```dockerfile
+# Build stage
+FROM public.ecr.aws/docker/library/node:22-alpine AS builder
+WORKDIR /app
+
+COPY package.json bun.lockb ./
+RUN corepack enable && corepack prepare bun@latest --activate
+RUN bun install --frozen-lockfile
+
+COPY . .
+RUN bun run build
+
+# Production stage
+FROM public.ecr.aws/docker/library/node:22-alpine AS runner
+WORKDIR /app
+
+ENV NODE_ENV=production
+ENV HOSTNAME=0.0.0.0
+ENV PORT=3000
+
+RUN addgroup --system --gid 1001 nodejs
+RUN adduser --system --uid 1001 nextjs
+
+COPY --from=builder /app/public ./public
+COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
+COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
+
+USER nextjs
+
+EXPOSE 3000
+
+CMD ["node", "server.js"]
+```
+
+Add `.dockerignore`:
+
+```
+.git
+node_modules
+.next
+.DS_Store
+cdk.out
+stack
+```
+
+Reference: [Next.js Docker Deployment](https://nextjs.org/docs/app/guides/docker)
+
+## 4. Install Thunder
+
+```bash
+bun add @thunder-so/thunder --development
+```
+
+## 5. Create Stack File
+
+Create `stack/prod.ts`:
+
+```typescript
+import { Cdk, Fargate, type FargateProps } from '@thunder-so/thunder';
+
+const config: FargateProps = {
+  env: {
+    account: '123456789012',  // Your AWS account ID
+    region: 'us-east-1',
+  },
+  application: 'myapp',
+  service: 'web',
+  environment: 'prod',
+
+  rootDir: '.',
+
+  serviceProps: {
+    dockerFile: 'Dockerfile',
+    architecture: Cdk.aws_ecs.CpuArchitecture.ARM64,
+    cpu: 512,        // 0.5 vCPU
+    memorySize: 1024, // 1 GB
+    port: 3000,
+    desiredCount: 1,
+    healthCheckPath: '/',
+  },
+};
+
+new Fargate(
+  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
+```
+
+CDK builds your Docker image, pushes it to ECR, and deploys to Fargate. The ALB DNS name is output:
+
+```
+Outputs:
+myapp-web-prod-stack.LoadBalancerDNS = myapp-web-prod-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**
+
+Update your stack:
+
+```typescript
+const config: FargateProps = {
+  // ...
+  domain: 'app.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
+
+## Environment Variables
+
+```typescript
+serviceProps: {
+  // ...
+  variables: [
+    { NODE_ENV: 'production' },
+    { NEXT_PUBLIC_API_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
+serviceProps: {
+  // ...
+  secrets: [
+    { key: 'DATABASE_URL', resource: 'arn:aws:secretsmanager:us-east-1:123456789012:secret:/myapp/DATABASE_URL-abc123' },
+  ],
+},
+```
+
+## Scaling
+
+Increase task count for high availability:
+
+```typescript
+serviceProps: {
+  desiredCount: 2,  // Run 2 containers
+  cpu: 1024,        // 1 vCPU per task
+  memorySize: 2048, // 2 GB per task
+},
+```
+
+See [Fargate CPU/memory combinations](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-cpu-memory-error.html).
+
+## Cost Estimate
+
+Minimal deployment (1 task, `us-east-1`, no free tier):
+
+| Component | Monthly |
+|---|---|
+| Fargate (1 task, 0.5 vCPU / 1 GB) | ~$15 |
+| Application Load Balancer | ~$22 |
+| CloudWatch Logs | <$1 |
+| Route53 | $0.50 |
+| **Total** | **~$38/month** |
+
+## Related
+
+- [fargate-basic.md](../fargate-basic.md) - Fargate construct reference
+- [fargate-nixpacks.md](../fargate-nixpacks.md) - Auto-generate Dockerfiles with Nixpacks
+- [fargate-full.md](../fargate-full.md) - Full configuration reference
+- [nextjs-fargate-nixpacks.md](./nextjs-fargate-nixpacks.md) - Next.js on Fargate without writing a Dockerfile

package/docs/frameworks/nextjs-fargate-nixpacks.md

@@ -0,0 +1,113 @@
+# Deploy Next.js to AWS Fargate with Nixpacks
+
+Run your Next.js app on [AWS ECS Fargate](https://aws.amazon.com/fargate/) without writing a Dockerfile. [Nixpacks](https://nixpacks.com/) auto-detects your project and generates an optimized container image.
+
+## 1. Create a New Next.js Project
+
+```bash
+bunx create-next-app@latest my-nextjs-app
+cd my-nextjs-app
+```
+
+Reference: [Next.js Installation Docs](https://nextjs.org/docs/getting-started/installation)
+
+## 2. Install Nixpacks CLI
+
+```bash
+# macOS / Linux
+curl -sSL https://nixpacks.com/install.sh | bash
+
+# or via npm
+npm install -g nixpacks
+```
+
+Verify:
+```bash
+nixpacks --version
+```
+
+Reference: [Nixpacks Installation](https://nixpacks.com/docs/install)
+
+## 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: {
+    architecture: Cdk.aws_ecs.CpuArchitecture.ARM64,
+    cpu: 512,
+    memorySize: 1024,
+    port: 3000,
+    desiredCount: 1,
+    healthCheckPath: '/',
+  },
+
+  buildProps: {
+    buildSystem: 'Nixpacks',
+    runtime_version: '22',
+    startcmd: 'bun start',
+  },
+};
+
+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
+```
+
+Nixpacks generates a Dockerfile during `cdk synth`, then CDK builds and deploys it.
+
+## 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-nixpacks.md](../fargate-nixpacks.md) - Nixpacks reference
+- [nextjs-fargate-dockerfile.md](./nextjs-fargate-dockerfile.md) - Next.js with custom Dockerfile