/infra-iac-sst

name: infra-iac-sst
description: SST (Ion) infrastructure-as-code — TypeScript-first serverless on AWS with Pulumi, resource linking, and live Lambda dev

SST (Ion) Patterns

> **Quick Guide:** SST v3 (Ion) is TypeScript-first infrastructure-as-code for AWS, powered by Pulumi/Terraform (not CDK/CloudFormation). Define your entire app in `sst.config.ts` using high-level components (`sst.aws.Function`, `sst.aws.ApiGatewayV2`, `sst.aws.Bucket`, `sst.aws.Dynamo`, etc.). Use **resource linking** (`link: [bucket]` + `Resource.MyBucket.name`) for type-safe, permission-aware access between components. Use `sst dev` for live Lambda development with sub-10ms reloads. Use `$app.stage` for multi-environment isolation. Use `transform` to customize underlying Pulumi resources.

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST use resource linking (`link` + `Resource.*`) to connect components — NEVER hardcode ARNs, table names, or bucket names)**

**(You MUST use `$app.stage` for environment isolation — NEVER share resources across stages without explicit intent)**

**(You MUST use `sst dev` for local development — it provides live Lambda proxying with sub-10ms reloads against real AWS resources)**

**(You MUST use `sst secret set` for secrets — NEVER put secrets in `sst.config.ts`, `.env` files committed to git, or environment variables)**

**(You MUST use `transform` to customize underlying resources — NEVER reach for raw Pulumi resources when an SST component exists)**

</critical_requirements>

---

Examples

• [Core Patterns](examples/core.md) — sst.config.ts structure, Function, resource linking, $app globals, secrets, multi-stage
• [API & Data](examples/api-data.md) — ApiGatewayV2, Dynamo, Bucket, Queue, Topic, Cron, authorization
• [Deployment & DevOps](examples/deployment.md) — sst deploy, CI/CD, removal policies, transforms, Vpc, Cluster, frontend frameworks
• [Quick Reference](reference.md) — CLI commands, component cheat sheet, global helpers, named constants

---

**Auto-detection:** SST, sst.config.ts, sst.aws.Function, sst.aws.ApiGatewayV2, sst.aws.Bucket, sst.aws.Dynamo, sst.aws.Queue, sst.aws.Topic, sst.aws.Cron, sst.aws.Nextjs, sst.aws.Remix, sst.aws.Astro, sst.aws.StaticSite, sst.aws.Vpc, sst.aws.Cluster, sst.aws.Postgres, sst.aws.Router, sst.Linkable, Resource from sst, sst dev, sst deploy, sst remove, sst secret, $app.stage, $transform, $concat, $interpolate, resource linking, live Lambda, Ion

**When to use:**

• Defining AWS infrastructure in TypeScript with high-level components
• Deploying serverless applications (Lambda, API Gateway, DynamoDB, S3, SQS, SNS)
• Deploying full-stack apps (Next.js, Remix, Astro, SvelteKit, SolidStart on AWS)
• Setting up live Lambda development with real AWS resources
• Managing multi-stage environments (dev, staging, production)
• Connecting infrastructure components with type-safe resource linking

**When NOT to use:**

• Multi-cloud infrastructure spanning many providers (SST is AWS-focused with limited Cloudflare support)
• Existing Terraform/Pulumi codebases where SST abstraction adds no value
• Projects that need container-only deployments without serverless components

**Key patterns covered:**

• `sst.config.ts` structure (`app()` + `run()` functions)
• Resource linking: `link` property + `Resource.*` SDK
• Live Lambda development with `sst dev`
• AWS components: Function, ApiGatewayV2, Dynamo, Bucket, Queue, Topic, Cron
• Frontend deployments: Nextjs, Remix, Astro, StaticSite
• Multi-stage isolation with `$app.stage`
• Transforms for customizing underlying Pulumi resources
• Secrets management with `sst secret`
• Custom linkables with `sst.Linkable` and `Linkable.wrap`
• Global helpers: `$app`, `$dev`, `$concat`, `$interpolate`, `$resolve`, `$transform`

---

<philosophy>

Philosophy

SST v3 (Ion) replaces CDK/CloudFormation with Pulumi/Terraform for dramatically faster deployments and a simpler programming model. The core ideas:

1. **One config file** — Your entire app is defined in `sst.config.ts`. Infrastructure, frontends, and functions all declared together in TypeScript with loops, conditionals, and functions. 2. **Components over constructs** — High-level `sst.aws.*` components encapsulate best practices (IAM, logging, monitoring). Use `transform` to reach into underlying resources when defaults aren't enough. 3. **Resource linking** — The killer feature. `link: [bucket]` automatically grants IAM permissions and injects type-safe references. Access via `Resource.MyBucket.name` at runtime. No manual ARN passing or environment variable wiring. 4. **Stage-based isolation** — Every developer gets their own stage (`sst dev` creates a personal stack). `$app.stage` drives resource naming. Production uses `sst deploy --stage production`. 5. **Live dev against real AWS** — `sst dev` replaces Lambda functions with stubs that proxy to your local machine. Changes reload in under 10ms. No local emulation — your code runs against real DynamoDB, S3, SQS.

**When to use SST:**

• Serverless-first applications on AWS (Lambda, API Gateway, DynamoDB, S3, SQS, SNS)
• Full-stack apps deploying frontend frameworks (Next.js, Remix, Astro) to AWS
• Teams that want TypeScript infrastructure with minimal AWS boilerplate
• Projects needing fast local development loops against real cloud resources

**When NOT to use SST:**

• Multi-cloud infrastructure beyond AWS + Cloudflare (SST's multi-cloud support is limited)
• Container-only workloads with no serverless components (use raw Pulumi or Terraform)
• Existing large Terraform/Pulumi codebases where SST abstraction adds migration cost

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: sst.config.ts Structure

Every SST app has a single `sst.config.ts` with two functions: `app()` for metadata and `run()` for resou