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 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
  • Nuxt - Serverless full-stack with Lambda
  • Astro - Serverless full-stack SSR with Lambda
  • Template - Coolify-style templates
• CLI Commands
• Documentation
• License

Features

• Constructs: One-line deployment for Static, Lambda, Fargate, EC2, Nuxt, and Astro.
• 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.js, Astro (SSR), and extensibility for SvelteKit, TanStack 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);

Full-Stack Frameworks

Nuxt

Deploy Nuxt.js SSR applications with hybrid rendering - Lambda for server-side and S3 for static assets.

Best for: Vue-based full-stack applications with server-side rendering

AWS Resources:

• Lambda Function - SSR server
• S3 Bucket - Static assets
• CloudFront Distribution - Unified CDN
• API Gateway - HTTP API

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,
  },
  
  // Optional: Custom domain
  domain: 'example.com',
  globalCertificateArn: 'arn:aws:acm:us-east-1:...',
  hostedZoneId: 'Z123456789',
};

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

Astro

Deploy Astro SSR applications with the same infrastructure pattern as Nuxt.

Best for: Content-focused websites with server-side rendering and islands architecture

AWS Resources: Same as Nuxt

Example:

import { Cdk, Astro, type NuxtProps as 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,
  },
};

new Astro(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.

License

Apache-2.0