@thunder-so/thunder 1.1.0 → 1.3.0

package/README.md

@@ -342,6 +342,256 @@ new Astro(new Cdk.App(), 'myapp-web-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
+
+**AWS Resources:**
+- [Lambda Function](https://aws.amazon.com/lambda/) - SSR server with container support
+- [S3 Bucket](https://aws.amazon.com/s3/) - Static assets with OAC
+- [CloudFront Distribution](https://aws.amazon.com/cloudfront/) - Global CDN with custom domain
+- [API Gateway](https://aws.amazon.com/api-gateway/) - HTTP API for server functions
+- [Route53](https://aws.amazon.com/route53/) - DNS management (optional)
+- [ACM](https://aws.amazon.com/certificate-manager/) - SSL certificates (optional)
+
+**Supported Frameworks:**
+- [TanStack Start](https://tanstack.com/start) - Type-safe full-stack React framework
+- [Nuxt](https://nuxt.com/) - Vue-based full-stack framework
+- [Astro](https://astro.build/) - Content-focused web framework with islands architecture
+- [React Router v7](https://reactrouter.com/) - Full-stack React framework with nested routing
+- [SvelteKit](https://kit.svelte.dev/) - Svelte-based full-stack framework
+- [Solid Start](https://start.solidjs.com/) - SolidJS full-stack framework
+- [AnalogJS](https://analogjs.org/) - Angular-based full-stack framework
+
+#### TanStack Start
+
+**Example:**
+```typescript
+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:**
+```typescript
+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:**
+```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: '.',
+  
+  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);
+```
+
+#### React Router
+
+Deploy [React Router v7](https://reactrouter.com/) framework mode applications with server-side rendering and API routes.
+
+**Best for:** React applications with nested routing, server-side rendering, and modern React Router patterns
+
+**AWS Resources:** Same as [TanStack Start](#tanstack-start)
+
+**Example:**
+```typescript
+import { Cdk, ReactRouter, type ReactRouterProps } from '@thunder-so/thunder';
+
+const config: ReactRouterProps = {
+  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 ReactRouter(new Cdk.App(), 'myapp-web-prod-stack', config);
+```
+
+#### SvelteKit
+
+**Example:**
+```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: '.',
+  
+  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:**
+```typescript
+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:**
+```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: '.',
+  
+  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](https://coolify.io/)-style templates on EC2. Automatically fetches and hydrates Docker Compose templates from the [Coolify templates repository](https://github.com/coollabsio/coolify).

package/index.ts

@@ -4,9 +4,11 @@ export { Lambda } from './stacks/LambdaStack';
 export { Fargate } from './stacks/FargateStack';
 export { Ec2 } from './stacks/Ec2Stack';
 export { Template } from './stacks/TemplateStack';
-export { Nuxt } from './stacks/NuxtStack';
-export { Astro } from './stacks/AstroStack';
 export { Vpc } from './stacks/VpcStack';
+export { ServerlessStack } from './stacks/ServerlessStack';
+
+// Serverless framework stacks (new unified abstraction)
+export * from './lib/serverless';
 
 // Types
 export type { StaticProps } from './types/StaticProps';
@@ -14,10 +16,17 @@ export type { LambdaProps } from './types/LambdaProps';
 export type { FargateProps } from './types/FargateProps';
 export type { Ec2Props } from './types/Ec2Props';
 export type { TemplateProps } from './types/TemplateProps';
-export type { NuxtProps } from './types/NuxtProps';
-export type { NuxtProps as AstroProps } from './types/NuxtProps';
 
-// Template utilities
+// Serverless framework types
+export type { ServerlessBaseProps as NuxtProps } from './types/ServerlessProps';
+export type { ServerlessBaseProps as AstroProps } from './types/ServerlessProps';
+export type { ServerlessBaseProps as TanStackStartProps } from './types/ServerlessProps';
+export type { ServerlessBaseProps as SvelteKitProps } from './types/ServerlessProps';
+export type { ServerlessBaseProps as SolidStartProps } from './types/ServerlessProps';
+export type { ServerlessBaseProps as AnalogJSProps } from './types/ServerlessProps';
+export type { ServerlessBaseProps, ServerlessServerProps, ServerlessClientProps } from './types/ServerlessProps';
+
+// Coolify Template utilities
 export { fetchTemplate } from './lib/template/template/fetch';
 export { hydrateTemplate } from './lib/template/template/hydrate';
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thunder-so/thunder",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "CDK library for deploying web applications on AWS",
   "keywords": [
     "aws",

package/.agents/CLI.md

@@ -1,65 +0,0 @@
-# Thunder CLI Scope
-
-The Thunder CLI (`th`) is the primary interface for developing, deploying, and managing applications built with `@thunder-so/thunder`. It is designed to be a thin, context-aware wrapper around the AWS CDK, providing a developer experience similar to SST but tailored for the Thunder ecosystem.
-
-## Core Mandates
-
-1.  **Context-Awareness:** [x] **DONE**: The CLI automatically detects the current environment, application, and service from the repository structure or configuration, minimizing repetitive flag usage.
-2.  **Zero-Config Defaults:** [x] **DONE**: "It just works" out of the box with sensible defaults for AWS regions, accounts, and resource sizing.
-3.  **Local Dev Parity:** [ ] **TODO**: Enables a local development loop that closely mirrors production, including live Lambda iteration (future scope) and local emulation of static sites.
-
-## Command Reference
-
-### `th init`
-- [ ] **TODO**: Scaffolds a new Thunder project or adds a new service to an existing monorepo.
-
--   **Usage:** `th init [template] [name]`
--   **Features:**
-    -   Detects if running in an existing workspace (monorepo).
-    -   Prompts for project type: `static`, `lambda`, `fargate`, `nuxt`, `astro`, `ec2`, `template`.
-    -   Generates `thunder.config.ts` (or updates it).
-    -   Creates necessary `bin/*.ts` entry points.
-    -   Sets up `.gitignore` and `package.json` scripts.
-
-### `th deploy`
-- [ ] **TODO**: Deploys the application to AWS.
-
--   **Usage:** `th deploy [--stage <stage>] [--filter <service>]`
--   **Features:**
-    -   **Stage Management:** defaults to `dev` for local, but supports `prod`, `staging`, `pr-*`.
-    -   **Context-Driven:** [x] **DONE**: Reads `bin/*.ts` files to determine which stacks to deploy.
-    -   **Metadata Push:** [x] **DONE**: Updates the `thunder-discovery` bucket with new resource ARNs and endpoints after successful deployment.
-    -   **Output:** Prints critical URLs (CloudFront, API Gateway, ALB) to the console.
-
-### `th destroy`
-- [ ] **TODO**: Tears down resources.
-
--   **Usage:** `th remove [--stage <stage>] [--filter <service>]`
--   **Features:**
-    -   **Safety Checks:** Prompts for confirmation, especially for `prod` stages or stateful resources (RDS, S3).
-    -   **Metadata Cleanup:** Removes entries from the `thunder-discovery` bucket.
-
-## Implementation Details
-
-### Context Resolution (`bin/*.ts`)
-- [x] **DONE**: The CLI relies on the convention of `bin/<type>.ts` files. 
--   `th deploy` scans `bin/` directory.
--   It executes these scripts using `ts-node` or `tsx`.
--   The scripts instantiate the Stacks (e.g., `NuxtStack`, `FargateStack`).
--   The CLI injects context (app, env, service, account, region) via environment variables or context context keys.
-
-### CLI Architecture
-- [ ] **TODO**:
--   **Runtime:** Node.js
--   **Core Libs:** `aws-cdk` (programmatic), `aws-sdk` (v3), `inquirer` (prompts), `commander` (args), `ink` (TUI).
--   **Build:** `esbuild` for fast bundling of Lambda code during `th dev`.
-
-## Comparison with SST
-
-| Feature | SST CLI | Thunder CLI |
-| :--- | :--- | :--- |
-| **Engine** | Pulumi / Terraform (v3) | AWS CDK (Native) |
-| **Language** | TypeScript / Python / Go | TypeScript (Strict) |
-| **State** | Cloud State Backend | CloudFormation + S3 Metadata |
-| **Local Dev** | Live Lambda (Multiplexing) | Hotswap + Local Framework Server |
-| **Constructs** | Broad (150+ providers) | Focused (AWS Web patterns) |

package/.agents/METADATA.md

@@ -1,75 +0,0 @@
-# Metadata Discovery
-
-Thunder implements an "SST-style" discovery mechanism to enable the Thunder CLI and potential future Thunder Console to automatically identify and interact with deployed resources without relying on manual tagging or complex CloudFormation stack queries.
-
-## How Thunder Tags Deployments
-
-- [x] **DONE**: Thunder uses a state-based approach rather than traditional AWS resource tags for discovery.
-
-### State Storage
-When you deploy a Thunder service, it automatically stores its deployment state in a centralized S3 bucket named `thunder-discovery-<account>-<region>`.
-
-### Key Structure
-Metadata files are stored with the following hierarchy:
-`apps/<application>/<environment>/<service>/metadata.json`
-
-### Metadata Content
-The `metadata.json` file contains a standardized set of properties that align with the service's `CfnOutput` names:
-```json
-{
-  "id": "myapp-prod-web",
-  "application": "myapp",
-  "service": "web",
-  "environment": "prod",
-  "region": "us-east-1",
-  "timestamp": "2026-03-04T12:00:00.000Z",
-  "type": "Nuxt",
-  "DistributionId": "E1234567890",
-  "DistributionUrl": "https://d123.cloudfront.net",
-  "Route53Domain": "https://myapp.com",
-  "CodePipelineName": "myapp-prod-web-pipeline"
-}
-```
-
-## How the CLI/Console Discovers Apps
-
-1.  **Bucket Resolution**: The tool determines the discovery bucket name based on the current AWS account and region.
-2.  **S3 Scanning**: It lists the objects in the bucket under the `apps/` prefix.
-3.  **Metadata Parsing**: It reads the `metadata.json` files to discover:
-    - All deployed Thunder apps.
-    - Their environments/stages.
-    - Their individual services and associated resource IDs/URLs.
-4.  **Automatic Discovery**: Because the `DiscoveryConstruct` is embedded in every Thunder stack, new services and updates are automatically reflected in S3 upon successful deployment.
-
-## Implementation Details
-
-- [x] **DONE**: **`DiscoveryConstruct`**: A shared construct located in `lib/constructs/discovery.ts`.
-- [x] **DONE**: **`BucketDeployment`**: Uses `aws-s3-deployment` to upload `Source.jsonData` during the CDK deployment phase.
-- [x] **DONE**: **Standardization**: Metadata field names are strictly aligned with `CfnOutput` logical IDs (e.g., `DistributionId`, `ServiceUrl`).
-- [x] **DONE**: Each deployment stores its metadata in a centralized S3 bucket (`thunder-discovery-<account>-<region>`). 
-
-Metadata includes:
-- [x] App identity (application, service, environment)
-- [x] Resource ARNs, IDs and URLs (Aligned with `CfnOutput` names)
-- [x] Deployment timestamps
-- [x] Framework-specific metadata
-- [x] Route53 domain integration
-
-
-## ISSUES:
-
-7:11:10 PM | CREATE_FAILED        | Custom::CDKBucketDeployment               | Discovery/StoreMet...omResource/Default
-Received response status [FAILED] from custom resource. Message returned: Command '['/opt/awscli/aws', 's3', 'sync', '/tmp/tmpxgahyp87/contents', 's3://thunder-discovery-047719662375-us-east
--1/apps/nuxt3/dev/fargate']' returned non-zero exit status 1. (RequestId: afc6bb52-d373-4b97-9a7d-36d0ab9b9425)
-7:11:10 PM | ROLLBACK_IN_PROGRESS | AWS::CloudFormation::Stack                | nuxt3-fargate-dev-stack
-The following resource(s) failed to create: [DiscoveryStoreMetadataCustomResource5F6695DB, FargateFargateService7449B65B]. Rollback requested by user.
-7:11:10 PM | ROLLBACK_IN_PROGRESS | AWS::CloudFormation::Stack                | nuxt3-fargate-dev-stack
-The following resource(s) failed to create: [DiscoveryStoreMetadataCustomResource5F6695DB, FargateFargateService7449B65B]. Rollback requested by user.
-7:11:37 PM | DELETE_FAILED        | Custom::CDKBucketDeployment               | Discovery/StoreMet...omResource/Default
-Received response status [FAILED] from custom resource. Message returned: Command '['/opt/awscli/aws', 's3', 'rm', 's3://thunder-discovery-047719662375-us-east-1/apps/nuxt3/dev/fargate', '--
-recursive']' returned non-zero exit status 1. (RequestId: f9383113-0976-4fe3-af60-bcefbf14d514)
-
-❌  nuxt3-fargate-dev-stack failed: ToolkitError: The stack named nuxt3-fargate-dev-stack failed creation, it may need to be manually deleted from the AWS console: ROLLBACK_FAILED (The following resource(s) failed to delete: [DiscoveryStoreMetadataCustomResource5F6695DB]. ): Received response status [FAILED] from custom resource. Message returned: Command '['/opt/awscli/aws', 's3', 'sync', '/tmp/tmpxgahyp87/contents', 's3://thunder-discovery-047719662375-us-east-1/apps/nuxt3/dev/fargate']' returned non-zero exit status 1. (RequestId: afc6bb52-d373-4b97-9a7d-36d0ab9b9425), Received response status [FAILED] from custom resource. Message returned: Command '['/opt/awscli/aws', 's3', 'rm', 's3://thunder-discovery-047719662375-us-east-1/apps/nuxt3/dev/fargate', '--recursive']' returned non-zero exit status 1. (RequestId: f9383113-0976-4fe3-af60-bcefbf14d514)
-
-The following resource(s) failed to delete: [DiscoveryStoreMetadataCustomResource5F6695DB].
-Received response status [FAILED] from custom resource. Message returned: Command '['/opt/awscli/aws', 's3', 'rm', 's3://thunder-discovery-047719662375-us-east-1/apps/nuxt3/dev/fargate', '--recursive']' returned non-zero exit status 1. (RequestId: f9383113-0976-4fe3-af60-bcefbf14d514)