thunder

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, Lambda Functions, Containers on Fargate and EC2, and Serverless Full-stack Frameworks.

Table of Contents

• Features
• Supported Frameworks & Patterns
• Quick Start
• Stacks
  • Static - S3 + CloudFront + Route53
  • Lambda - API Gateway + Lambda
  • Fargate - ECS Fargate + ALB + CloudFront
  • EC2 - EC2 + Docker + Elastic IP
  • Serverless Frameworks - Full-stack meta-frameworks with Lambda + S3 + CloudFront
  • Template - Coolify-style templates
• CLI Commands
• Documentation
• License

Features

• 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 distributions with OAC, security headers, and edge optimizations.
• Built-in CI/CD: Optional AWS CodePipeline integration with GitHub support.

Supported Frameworks & Patterns

• Static: Vite (React, Vue, Svelte, Solid), Next.js (SSG), Astro (SSG), Gatsby.
• Serverless: Node.js Lambda, Bun, Container-based Lambda.
• Containers: ECS Fargate with ALB, Docker on EC2 with Elastic IP.
• Full-stack SSR: Nuxt, Astro, TanStack Start, SvelteKit, Solid Start, AnalogJS.

Quick Start

1. Install

bun add @thunder-so/thunder --development

2. Initialize

npx th init

3. Configure

Create a stack file (e.g., stack/dev.ts):

import { Cdk, Static, type StaticProps } from "@thunder-so/thunder";

const myApp: StaticProps = {
  env: {
    account: "123456789012",
    region: "us-east-1",
  },
  application: "myapp",
  service: "web",
  environment: "prod",

  rootDir: ".",
  outputDir: "dist",
};

new Static(
  new Cdk.App(),
  `${myApp.application}-${myApp.service}-${myApp.environment}-stack`,
  myApp,
);

4. Deploy

npx cdk deploy --app "npx tsx stack/dev.ts" --profile default

Stacks

Static

Deploy static websites to S3 with CloudFront CDN and Route53 DNS.

Best for: Static sites, SPAs, JAMstack applications

AWS Resources:

• S3 Bucket - Static file hosting
• CloudFront Distribution - Global CDN with caching
• Route53 - DNS management (optional)
• ACM Certificate - SSL/TLS certificates (optional)
• Lambda@Edge - Request/response manipulation (optional)

Example:

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",

  // Optional: Custom domain
  domain: "example.com",
  globalCertificateArn: "arn:aws:acm:us-east-1:...",
  hostedZoneId: "Z123456789",

  // Optional: Lambda@Edge for redirects/headers/rewrites
  redirects: [{ source: "/old", destination: "/" }],
  rewrites: [{ source: "/old", destination: "/new" }],
  headers: [{ path: "/*", name: "X-Custom-Header", value: "value" }],
};

new Static(new Cdk.App(), "myapp-web-prod-stack", config);

Lambda

Deploy serverless functions with API Gateway and optional Lambda Function URL.

Best for: Serverless APIs, microservices, event-driven applications

AWS Resources:

• Lambda Function - Compute layer
• API Gateway - HTTP API with custom domain support
• CloudWatch Logs - Logging and monitoring
• Secrets Manager - Secure secret injection (optional)

Example:

import { Cdk, Lambda, type LambdaProps } from "@thunder-so/thunder";

const config: LambdaProps = {
  env: { account: "123456789012", region: "us-east-1" },
  application: "myapp",
  service: "api",
  environment: "prod",
  rootDir: ".",

  functionProps: {
    runtime: Cdk.aws_lambda.Runtime.NODEJS_22_X,
    architecture: Cdk.aws_lambda.Architecture.ARM_64,
    codeDir: "src",
    handler: "index.handler",
    memorySize: 512,
    timeout: 30,
    url: true, // Enable function URL
    keepWarm: true, // Prevent cold starts
    variables: [{ NODE_ENV: "production" }],
    secrets: [{ key: "DATABASE_URL", resource: "arn:aws:secretsmanager:..." }],
  },

  // Optional: Custom domain
  domain: "api.example.com",
  regionalCertificateArn: "arn:aws:acm:us-east-1:...",
  hostedZoneId: "Z123456789",
};

new Lambda(new Cdk.App(), "myapp-api-prod-stack", config);

Fargate

Deploy containerized applications on ECS Fargate with Application Load Balancer and CloudFront.

Best for: Containerized web applications, microservices, long-running processes

AWS Resources:

• ECS Cluster - Container orchestration
• Fargate Task - Serverless containers
• Application Load Balancer - Traffic distribution
• ECR Repository - Container registry (via CodePipeline)
• CloudWatch Logs - Container logging

Example:

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: {
    architecture: Cdk.aws_ecs.CpuArchitecture.ARM64,
    desiredCount: 2,
    cpu: 512, // 0.5 vCPU
    memorySize: 1024, // 1 GB
    port: 3000,
    healthCheckPath: "/health",
    variables: [{ NODE_ENV: "production" }],
    dockerFile: "Dockerfile",
  },

  // Optional: Custom domain
  domain: "api.example.com",
  globalCertificateArn: "arn:aws:acm:us-east-1:...",
  hostedZoneId: "Z123456789",
};

new Fargate(new Cdk.App(), "myapp-api-prod-stack", config);

EC2

Deploy Docker containers on EC2 instances with Elastic IP for simple, cost-effective hosting.

Best for: Single-instance applications, development environments, simple Docker deployments

AWS Resources:

• EC2 Instance - Virtual server
• Elastic IP - Static public IP
• VPC - Network isolation
• Security Group - Firewall rules
• Route53 - DNS records (optional)

Example:

import { Cdk, Ec2, type Ec2Props } from "@thunder-so/thunder";

const config: Ec2Props = {
  env: { account: "123456789012", region: "us-east-1" },
  application: "myapp",
  service: "api",
  environment: "prod",
  rootDir: ".",

  serviceProps: {
    instanceType: "t3.micro",
    port: 3000,
    authorizedKeys: ["ssh-rsa AAAAB3... [email protected]"],
    dockerFile: "Dockerfile",
    variables: [{ NODE_ENV: "production" }],
  },

  // Optional: Custom domain with SSL
  domain: "api.example.com",
  hostedZoneId: "Z123456789",
  acmeEmail: "[email protected]", // For Let's Encrypt
};

new Ec2(new Cdk.App(), "myapp-api-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 - SSR server with container support
• S3 Bucket - Static assets with OAC
• CloudFront Distribution - Global CDN with custom domain
• API Gateway - HTTP API for server functions
• Route53 - DNS management (optional)
• ACM - SSL certificates (optional)

Supported Frameworks:

• TanStack Start - Type-safe full-stack React framework
• Nuxt - Vue-based full-stack framework
• Astro - Content-focused web framework with islands architecture
• SvelteKit - Svelte-based full-stack framework
• Solid Start - SolidJS full-stack framework
• AnalogJS - Angular-based full-stack framework

TanStack Start

Example:

import {
  Cdk,
  TanStackStart,
  type TanStackStartProps,
} from "@thunder-so/thunder";

const config: TanStackStartProps = {
  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,
    variables: [{ NODE_ENV: "production" }],
  },

  // Optional: Custom domain
  domain: "myapp.com",
  globalCertificateArn: "arn:aws:acm:us-east-1:...",
  hostedZoneId: "Z123456789",
};

new TanStackStart(new Cdk.App(), "myapp-web-prod-stack", config);

Nuxt

Example:

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,
    streaming: true,
    variables: [{ NODE_ENV: "production" }],
    secrets: [{ key: "DATABASE_URL", resource: "arn:aws:secretsmanager:..." }],
  },

  // Optional: Custom domain
  domain: "myapp.com",
  globalCertificateArn: "arn:aws:acm:us-east-1:...",
  hostedZoneId: "Z123456789",
};

new Nuxt(new Cdk.App(), "myapp-web-prod-stack", config);

Astro

Example:

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: ".",

  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 Astro(new Cdk.App(), "myapp-web-prod-stack", config);

SvelteKit

Example:

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: ".",

  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 SvelteKit(new Cdk.App(), "myapp-web-prod-stack", config);

Solid Start

Example:

import { Cdk, SolidStart, type SolidStartProps } from "@thunder-so/thunder";

const config: SolidStartProps = {
  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 SolidStart(new Cdk.App(), "myapp-web-prod-stack", config);

AnalogJS

Example:

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: ".",

  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 AnalogJS(new Cdk.App(), "myapp-web-prod-stack", config);

Template

Deploy Coolify-style templates on EC2. Automatically fetches and hydrates Docker Compose templates from the Coolify templates repository.

Best for: Self-hosted applications, databases, dev tools (e.g., n8n, WordPress, databases)

AWS Resources: Same as EC2

Example:

import {
  Cdk,
  Template,
  type TemplateProps,
  fetchTemplate,
  hydrateTemplate,
} from "@thunder-so/thunder";
import { InstanceType, InstanceClass, InstanceSize } from "aws-cdk-lib/aws-ec2";

async function main() {
  // Fetch template from Coolify repository
  const { parsed: parsedTemplate, port } = await fetchTemplate("n8n");

  // Hydrate template with variables
  const hydrateResult = hydrateTemplate(parsedTemplate, {
    domain: "n8n.example.com",
    fallbackPort: port,
  });

  const config: TemplateProps = {
    env: { account: "123456789012", region: "us-east-1" },
    application: "myapp",
    service: "n8n",
    environment: "prod",

    templateSlug: "n8n",
    instanceType: InstanceType.of(InstanceClass.T3, InstanceSize.MICRO),
    authorizedKeys: ["ssh-rsa AAAAB3... [email protected]"],
    hydrateResult,

    // Optional: Custom domain with SSL
    domain: "n8n.example.com",
    hostedZoneId: "Z123456789",
    acmeEmail: "[email protected]",
  };

  new Template(new Cdk.App(), "myapp-n8n-prod-stack", config);
}

main();

Available Templates: See the Coolify templates repository for available templates.

CLI Commands

| Command | Description | | :----------- | :-------------------------------- | | th init | Scaffold a new project or service | | th deploy | Deploy stacks to AWS | | th destroy | Remove resources from AWS |

Documentation

For detailed documentation on each construct and advanced configurations, see the Wiki.

Static

| Guide | Description | | :---------------------------------------------------------- | :------------------------------------------------------ | | static-basic.md | Deploy a static site or SPA to S3 + CloudFront | | static-edge-functions.md | Redirects, rewrites, and custom headers via Lambda@Edge | | static-full.md | Full StaticProps configuration reference |

Lambda

| Guide | Description | | :-------------------------------------------------- | :------------------------------------------------ | | lambda-basic.md | Deploy a serverless API with Lambda + API Gateway | | lambda-containers.md | Container images and Bun runtime | | lambda-full.md | Full LambdaProps configuration reference |

Fargate

| Guide | Description | | :------------------------------------------------ | :-------------------------------------------- | | fargate-basic.md | Deploy a containerized service on ECS Fargate | | fargate-nixpacks.md | Auto-generate Dockerfiles with Nixpacks | | fargate-full.md | Full FargateProps configuration reference |

Serverless (Full-Stack Frameworks)

| Guide | Description | | :------------------------------------ | :----------------------------------------- | | serverless.md | Deploy full-stack meta-frameworks with SSR |

Framework Guides

Static Deployment:

• Next.js Static
• Astro Static

Serverless (Lambda + S3 + CloudFront):

• Nuxt
• Astro SSR
• TanStack Start
• SvelteKit
• Solid Start
• AnalogJS

Fargate (Containers):

• Next.js with Dockerfile
• Next.js with Nixpacks
• Astro
• Nuxt
• TanStack Start
• SvelteKit
• Solid Start
• AnalogJS

License

Apache-2.0