@thunder-so/thunder 1.3.0 → 1.3.2

package/docs/frameworks/sveltekit-fargate.md

@@ -0,0 +1,130 @@
+# Deploy SvelteKit to AWS Fargate
+
+Run your SvelteKit app with full SSR support on [AWS ECS Fargate](https://aws.amazon.com/fargate/) using Thunder's `Fargate` construct.
+
+## 1. Create a New SvelteKit Project
+
+```bash
+bunx sv create my-sveltekit-app
+cd my-sveltekit-app
+```
+
+Reference: [SvelteKit Creating a Project](https://svelte.dev/docs/kit/creating-a-project)
+
+## 2. Configure SvelteKit for Node
+
+Edit `svelte.config.js`:
+
+```javascript
+import adapter from '@sveltejs/adapter-node';
+
+export default {
+  kit: {
+    adapter: adapter()
+  }
+};
+```
+
+## 3. 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/build ./build
+COPY --from=builder /app/package.json ./
+
+EXPOSE 3000
+
+CMD ["bun", "run", "build"]
+```
+
+## 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: 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
+```
+
+## 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
+- [sveltekit-serverless.md](./sveltekit-serverless.md) - SvelteKit on Lambda

package/docs/frameworks/sveltekit-serverless.md

@@ -0,0 +1,120 @@
+# Deploy SvelteKit to AWS Lambda + S3 + CloudFront
+
+Deploy your SvelteKit app with server-side rendering to AWS using Thunder's `SvelteKit` 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 SvelteKit Project
+
+```bash
+bunx sv create my-sveltekit-app
+cd my-sveltekit-app
+```
+
+Reference: [SvelteKit Creating a Project](https://svelte.dev/docs/kit/creating-a-project)
+
+## 2. Install Lambda Adapter
+
+```bash
+bun add -D @foladayo/sveltekit-adapter-lambda
+```
+
+## 3. Configure SvelteKit for AWS Lambda
+
+Edit `svelte.config.js`:
+
+```javascript
+import adapter from '@foladayo/sveltekit-adapter-lambda';
+
+export default {
+  kit: {
+    adapter: adapter({
+      precompress: false,
+      serveStatic: true,  // Required: serves prerendered pages
+    })
+  }
+};
+```
+
+Reference: [@foladayo/sveltekit-adapter-lambda](https://www.npmjs.com/package/@foladayo/sveltekit-adapter-lambda)
+
+## 4. Build Your App
+
+```bash
+bun run build
+```
+
+This generates:
+- `build/` - Lambda handler (flat structure)
+- `build/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, SvelteKit, type SvelteKitProps } from '@thunder-so/thunder';
+
+const config: SvelteKitProps = {
+  env: {
+    account: '123456789012',
+    region: 'us-east-1',
+  },
+  application: 'myapp',
+  service: 'web',
+  environment: 'prod',
+  rootDir: '.',
+};
+
+new SvelteKit(
+  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: SvelteKitProps = {
+  // ...
+  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' },
+  ],
+},
+```
+
+## Important Notes
+
+- **`serveStatic: true` is required** - Without it, prerendered pages return 404
+- **`package.json` is auto-included** - The build output uses ESM and needs `"type": "module"`
+- **Requires Node.js 22+** - Use `Runtime.NODEJS_22_X`
+
+## Related
+
+- [serverless.md](../serverless.md) - Serverless construct overview
+- [lambda-basic.md](../lambda-basic.md) - Lambda construct reference

package/docs/frameworks/tanstack-start-fargate.md

@@ -0,0 +1,115 @@
+# Deploy TanStack Start to AWS Fargate
+
+Run your TanStack Start app with full SSR support on [AWS ECS Fargate](https://aws.amazon.com/fargate/) using Thunder's `Fargate` construct.
+
+## 1. Create a New TanStack Start Project
+
+```bash
+bunx create-tanstack-start my-app
+cd my-app
+```
+
+Reference: [TanStack Start Quick Start](https://tanstack.com/start/latest/docs/framework/react/quick-start)
+
+## 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/.output ./
+
+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
+- [tanstack-start-serverless.md](./tanstack-start-serverless.md) - TanStack Start on Lambda

package/docs/frameworks/tanstack-start-serverless.md

@@ -0,0 +1,205 @@
+# Deploy TanStack Start to AWS Lambda + S3 + CloudFront
+
+Deploy your TanStack Start app with server-side rendering to AWS using Thunder's `TanStackStart` 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 TanStack Start Project
+
+```bash
+bunx create-tanstack-start my-app
+cd my-app
+```
+
+Reference: [TanStack Start Quick Start](https://tanstack.com/start/latest/docs/framework/react/quick-start)
+
+## 2. Configure Nitro for AWS Lambda
+
+TanStack Start uses [Nitro](https://nitro.unjs.io/) for server-side rendering. You **must** explicitly set the `aws-lambda` preset - the default is `node-server` which won't work on Lambda.
+
+Edit `app.config.ts` (or create it if it doesn't exist):
+
+```typescript
+import { defineConfig } from '@tanstack/start/config';
+import { nitro } from 'nitro/vite';
+
+export default defineConfig({
+  vite: {
+    plugins: [
+      nitro({
+        preset: 'aws-lambda',  // Required for Lambda deployment
+      }),
+    ],
+  },
+});
+```
+
+**Alternative:** If using `@tanstack/nitro-v2-vite-plugin`:
+
+```typescript
+import { nitroV2Plugin } from '@tanstack/nitro-v2-vite-plugin';
+
+export default defineConfig({
+  vite: {
+    plugins: [
+      nitroV2Plugin({
+        preset: 'aws-lambda',
+      }),
+    ],
+  },
+});
+```
+
+Reference: [Nitro AWS Lambda Preset](https://nitro.build/deploy/providers/aws)
+
+## 3. Build Your App
+
+```bash
+bun run build
+```
+
+This generates:
+- `.output/server/` - Lambda handler
+- `.output/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, TanStackStart, type TanStackStartProps } from '@thunder-so/thunder';
+
+const config: TanStackStartProps = {
+  env: {
+    account: '123456789012',  // Your AWS account ID
+    region: 'us-east-1',
+  },
+  application: 'myapp',
+  service: 'web',
+  environment: 'prod',
+
+  rootDir: '.',
+};
+
+new TanStackStart(
+  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 outputs the CloudFront and API Gateway URLs:
+
+```
+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)
+
+Update your stack:
+
+```typescript
+const config: TanStackStartProps = {
+  // ...
+  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
+const config: TanStackStartProps = {
+  // ...
+  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' },
+  ],
+},
+```
+
+## Performance Tuning
+
+```typescript
+serverProps: {
+  memorySize: 1792,  // More memory = more CPU
+  timeout: 10,
+  keepWarm: true,    // Ping every 5 min to prevent cold starts
+  tracing: true,     // Enable AWS X-Ray
+},
+```
+
+## Container Mode (Optional)
+
+For larger apps, use Docker:
+
+Create `Dockerfile`:
+
+```dockerfile
+FROM public.ecr.aws/lambda/nodejs:22
+
+COPY .output/server/ ./
+
+CMD ["index.handler"]
+```
+
+Update your stack:
+
+```typescript
+serverProps: {
+  dockerFile: 'Dockerfile',
+  memorySize: 2048,
+},
+```
+
+## Troubleshooting
+
+**Error: `Runtime.HandlerNotFound: index.handler is undefined`**
+
+You forgot to set `preset: 'aws-lambda'` in your Nitro config. The default `node-server` preset outputs an HTTP server, not a Lambda handler.
+
+**Static assets not loading**
+
+Check that your build output is in `.output/public/`. Thunder automatically deploys this to S3 and routes `*.*` requests through CloudFront.
+
+## Related
+
+- [serverless.md](../serverless.md) - Serverless construct overview
+- [lambda-basic.md](../lambda-basic.md) - Lambda construct reference
+- [static-basic.md](../static-basic.md) - Static construct reference