# SST (Ion) — API & Data Patterns

> API Gateway, DynamoDB, S3, Queue, Topic, and Cron patterns. See [SKILL.md](../SKILL.md) for decision guidance.

**Related examples:**

- [Core Patterns](core.md) — sst.config.ts, resource linking, live dev, secrets
- [Deployment & DevOps](deployment.md) — CI/CD, transforms, removal policies, VPC

---

## ApiGatewayV2 — HTTP API

```typescript
async run() {
  const table = new sst.aws.Dynamo("Notes", {
    fields: { userId: "string", noteId: "string" },
    primaryIndex: { hashKey: "userId", rangeKey: "noteId" },
  });

  const api = new sst.aws.ApiGatewayV2("Api", {
    cors: true,
    domain: $app.stage === "production" ? "api.example.com" : undefined,
    accessLog: { retention: "1 month" },
  });

  // Add routes — handler string or object with config
  api.route("GET /notes", {
    handler: "src/notes/list.handler",
    link: [table],
  });
  api.route("POST /notes", {
    handler: "src/notes/create.handler",
    link: [table],
    memory: "512 MB",
  });
  api.route("GET /notes/{id}", "src/notes/get.handler");
  api.route("$default", "src/fallback.handler"); // Catch-all route

  return { apiUrl: api.url };
}
```

**Why good:** Each route gets its own Lambda function (fine-grained scaling and permissions), `$default` catches unmatched routes, custom domain only in production, access logs for debugging

---

## ApiGatewayV2 — Authorization

### JWT Authorization

```typescript
const api = new sst.aws.ApiGatewayV2("Api");

const jwtAuth = api.addAuthorizer({
  name: "jwt",
  jwt: {
    issuer: "https://auth.example.com/",
    audiences: ["https://api.example.com"],
  },
});

api.route("GET /public", "src/public.handler"); // No auth
api.route("GET /private", "src/private.handler", {
  auth: { jwt: { authorizer: jwtAuth.id } },
});
api.route("GET /admin", "src/admin.handler", {
  auth: { jwt: { authorizer: jwtAuth.id, scopes: ["admin:read"] } },
});
```

### IAM Authorization

```typescript
api.route("POST /internal", "src/internal.handler", {
  auth: { iam: true },
});
```

### Lambda Authorizer

```typescript
const customAuth = api.addAuthorizer({
  name: "custom",
  lambda: { function: "src/authorizer.handler" },
});

api.route("GET /protected", "src/protected.handler", {
  auth: { lambda: customAuth.id },
});
```

---

## Dynamo — DynamoDB Table

```typescript
const table = new sst.aws.Dynamo("Orders", {
  fields: {
    orderId: "string",
    customerId: "string",
    createdAt: "number",
  },
  primaryIndex: { hashKey: "orderId" },
  globalIndexes: {
    CustomerIndex: {
      hashKey: "customerId",
      rangeKey: "createdAt",
    },
  },
  stream: "new-and-old-images",
  deletionProtection: $app.stage === "production",
});

// Subscribe to stream events
table.subscribe("OrderProcessor", "src/process-order.handler", {
  filters: [{ eventName: ["INSERT"] }],
});
```

**Why good:** Global secondary index for querying by customer, stream captures all changes, subscriber filters to only process new inserts, deletion protection in production

```typescript
// BAD: No indexes, no stream, no protection
const table = new sst.aws.Dynamo("Orders", {
  fields: { orderId: "string" },
  primaryIndex: { hashKey: "orderId" },
});
```

**Why bad:** No secondary indexes means table scans for any non-PK query, no stream means no reactive processing, no deletion protection in production

---

## Dynamo — TTL (Auto-Expiry)

```typescript
const sessions = new sst.aws.Dynamo("Sessions", {
  fields: { sessionId: "string" },
  primaryIndex: { hashKey: "sessionId" },
  ttl: "expiresAt", // DynamoDB auto-deletes when expiresAt < now
});
```

```typescript
// Runtime — set TTL value
const SESSION_TTL_SECONDS = 3_600;

await client.send(
  new PutItemCommand({
    TableName: Resource.Sessions.name,
    Item: {
      sessionId: { S: id },
      expiresAt: {
        N: String(Math.floor(Date.now() / 1000) + SESSION_TTL_SECONDS),
      },
    },
  }),
);
```

---

## Bucket — S3 Storage

```typescript
const uploads = new sst.aws.Bucket("Uploads", {
  cors: {
    allowOrigins: ["https://example.com"],
    allowMethods: ["GET", "PUT"],
    allowHeaders: ["content-type"],
    maxAge: "1 day",
  },
});

// Subscribe to object events
uploads.notify({
  notifications: [
    {
      name: "ImageProcessor",
      function: "src/process-image.handler",
      events: ["s3:ObjectCreated:*"],
      filterPrefix: "images/",
    },
  ],
});
```

### Public Bucket

```typescript
// Public read access for all objects (static assets, public downloads)
const assets = new sst.aws.Bucket("Assets", {
  access: "public",
});
```

---

## Queue — SQS

```typescript
const dlq = new sst.aws.Queue("EmailDLQ");

const emailQueue = new sst.aws.Queue("EmailQueue", {
  visibilityTimeout: "5 minutes",
  dlq: { queue: dlq.arn, retry: 3 },
});

// Subscribe a handler to process messages
emailQueue.subscribe("EmailSender", "src/send-email.handler");
```

### FIFO Queue

```typescript
const orderQueue = new sst.aws.Queue("OrderQueue", {
  fifo: { contentBasedDeduplication: true },
});

orderQueue.subscribe("OrderProcessor", "src/process-order.handler");
```

### Sending Messages (Runtime)

```typescript
import { Resource } from "sst";
import { SQSClient, SendMessageCommand } from "@aws-sdk/client-sqs";

const sqs = new SQSClient({});

export async function handler() {
  await sqs.send(
    new SendMessageCommand({
      QueueUrl: Resource.EmailQueue.url,
      MessageBody: JSON.stringify({ to: "user@example.com", subject: "Hello" }),
    }),
  );
}
```

---

## Cron — Scheduled Tasks

```typescript
// Rate-based schedule
new sst.aws.Cron("DailyCleanup", {
  function: "src/cleanup.handler",
  schedule: "rate(1 day)",
});

// Cron expression (UTC)
new sst.aws.Cron("WeeklyReport", {
  function: {
    handler: "src/report.handler",
    timeout: "5 minutes",
    memory: "2048 MB",
  },
  schedule: "cron(0 9 ? * MON *)", // Every Monday at 9:00 AM UTC
});

// Disable in dev
new sst.aws.Cron("HourlySync", {
  function: "src/sync.handler",
  schedule: "rate(1 hour)",
  enabled: $app.stage === "production",
});
```

**Why good:** Cron disabled in non-production stages to avoid unnecessary executions, custom timeout/memory for heavy report, rate expression for simple intervals

---

## Function — Direct Lambda

```typescript
// Function with URL endpoint (no API Gateway)
const webhook = new sst.aws.Function("StripeWebhook", {
  handler: "src/webhook.handler",
  url: {
    cors: {
      allowOrigins: ["https://stripe.com"],
      allowMethods: ["POST"],
    },
  },
  timeout: "60 seconds",
  link: [ordersTable],
});

// Streaming response
const streamer = new sst.aws.Function("StreamResponse", {
  handler: "src/stream.handler",
  url: true,
  streaming: true,
});

// ARM64 for cost savings (~20% cheaper, often faster)
const compute = new sst.aws.Function("Compute", {
  handler: "src/compute.handler",
  architecture: "arm64",
  memory: "2048 MB",
});
```

---

## Combining Components

```typescript
async run() {
  // Data layer
  const table = new sst.aws.Dynamo("Tasks", {
    fields: { taskId: "string", status: "string" },
    primaryIndex: { hashKey: "taskId" },
    globalIndexes: {
      StatusIndex: { hashKey: "status" },
    },
    stream: "new-image",
  });

  const bucket = new sst.aws.Bucket("Files");

  // Async processing
  const queue = new sst.aws.Queue("TaskQueue");
  queue.subscribe("TaskWorker", {
    handler: "src/worker.handler",
    link: [table, bucket],
    timeout: "5 minutes",
  });

  // API layer
  const api = new sst.aws.ApiGatewayV2("Api");
  api.route("GET /tasks", {
    handler: "src/tasks/list.handler",
    link: [table],
  });
  api.route("POST /tasks", {
    handler: "src/tasks/create.handler",
    link: [table, queue],
  });
  api.route("POST /tasks/{id}/upload", {
    handler: "src/tasks/upload.handler",
    link: [bucket],
  });

  // React to changes
  table.subscribe("TaskNotifier", "src/notify.handler", {
    filters: [{ eventName: ["INSERT", "MODIFY"] }],
  });

  return { apiUrl: api.url };
}
```

**Why good:** Each handler gets only the permissions it needs via `link`, async work offloaded to queue, stream subscriber reacts to data changes, single `return` exposes the API URL

# SST (Ion) — Core Patterns

> Core configuration, resource linking, live dev, and secrets patterns. See [SKILL.md](../SKILL.md) for decision guidance.

**Related examples:**

- [API & Data](api-data.md) — ApiGatewayV2, Dynamo, Bucket, Queue, Topic, Cron
- [Deployment & DevOps](deployment.md) — CI/CD, transforms, removal policies, VPC, frontend frameworks

---

## sst.config.ts Structure

```typescript
/// <reference path="./.sst/platform/config.d.ts" />

export default $config({
  app(input) {
    return {
      name: "my-app",
      home: "aws",
      removal: input.stage === "production" ? "retain" : "remove",
      protect: input.stage === "production",
      providers: {
        aws: { region: "us-east-1" },
      },
    };
  },
  async run() {
    // All resources defined here
    const bucket = new sst.aws.Bucket("Uploads");

    const api = new sst.aws.Function("Api", {
      handler: "src/api.handler",
      link: [bucket],
      url: true,
    });

    // Returned values become outputs in .sst/outputs.json
    return {
      apiUrl: api.url,
      bucketName: bucket.name,
    };
  },
});
```

**Why good:** `app()` configures metadata and stage-aware policies (retain prod data, protect prod from accidental removal), `run()` defines all resources with TypeScript, return values create CLI-accessible outputs

```typescript
// BAD: Missing stage-aware policies
export default $config({
  app(input) {
    return {
      name: "my-app",
      home: "aws",
      // No removal or protect — production data can be accidentally deleted
    };
  },
  async run() {
    const bucket = new sst.aws.Bucket("Uploads");
    // No return — outputs not available to other tools
  },
});
```

**Why bad:** No `removal: "retain"` for production means `sst remove` deletes all S3 data, no `protect` means accidental removal is possible, no return value means no outputs for scripts or CI

---

## Resource Linking — Infrastructure Side

```typescript
// sst.config.ts
async run() {
  const table = new sst.aws.Dynamo("Notes", {
    fields: { userId: "string", noteId: "string" },
    primaryIndex: { hashKey: "userId", rangeKey: "noteId" },
  });

  const bucket = new sst.aws.Bucket("Attachments");

  // Link grants IAM permissions AND injects type-safe references
  new sst.aws.Function("Api", {
    handler: "src/api.handler",
    link: [table, bucket],
  });

  // Link to frontend frameworks (server-side only)
  new sst.aws.Nextjs("Web", {
    link: [table, bucket],
  });
}
```

**Why good:** `link` automatically generates IAM policies (Function gets DynamoDB + S3 access), injects resource metadata into function bundle, and creates `sst-env.d.ts` type definitions

---

## Resource Linking — Runtime Side

```typescript
// src/api.ts — handler code
import { Resource } from "sst";
import { DynamoDBClient, PutItemCommand } from "@aws-sdk/client-dynamodb";

const client = new DynamoDBClient({});

export async function handler(event: unknown) {
  // Resource.Notes.name is the DynamoDB table name — type-safe
  await client.send(
    new PutItemCommand({
      TableName: Resource.Notes.name,
      Item: {
        userId: { S: "user-123" },
        noteId: { S: "note-456" },
      },
    }),
  );

  // Resource.Attachments.name is the S3 bucket name
  console.log("Bucket:", Resource.Attachments.name);

  return { statusCode: 200, body: "Created" };
}
```

**Why good:** `Resource.*` is fully typed (autocomplete works), no hardcoded table/bucket names, no manual environment variable wiring, permissions already granted via `link`

```typescript
// BAD: Hardcoded resource names
const TABLE_NAME = "my-app-production-Notes";
await client.send(
  new PutItemCommand({
    TableName: TABLE_NAME, // Breaks across stages, no type safety
    Item: { userId: { S: "user-123" }, noteId: { S: "note-456" } },
  }),
);
```

**Why bad:** Hardcoded name breaks in dev/staging stages, no type safety, requires manual IAM policy management, no connection to SST infrastructure

---

## Custom Linkables

Link arbitrary values (API keys, config) or wrap raw Pulumi resources.

```typescript
// Link arbitrary values
const stripe = new sst.Linkable("Stripe", {
  properties: { publishableKey: "pk_live_xxx" },
});

new sst.aws.Function("Billing", {
  handler: "src/billing.handler",
  link: [stripe],
});
```

```typescript
// Runtime access
import { Resource } from "sst";
const key = Resource.Stripe.publishableKey;
```

```typescript
// Wrap a raw Pulumi resource to make it linkable
sst.Linkable.wrap(aws.dynamodb.Table, (table) => ({
  properties: { tableName: table.name },
  include: [
    sst.aws.permission({
      actions: ["dynamodb:*"],
      resources: [table.arn],
    }),
  ],
}));

// Now raw Pulumi tables can be linked like SST components
const rawTable = new aws.dynamodb.Table("Legacy", {
  /* ... */
});
new sst.aws.Function("Handler", {
  handler: "src/handler.handler",
  link: [rawTable],
});
```

**Why good:** `sst.Linkable` links arbitrary config, `Linkable.wrap` makes any Pulumi resource linkable with permissions — useful for AWS services without an SST component

---

## Secrets

```bash
# Set secrets (per-stage, encrypted in S3)
sst secret set DATABASE_URL "postgres://..."
sst secret set STRIPE_SECRET_KEY "sk_live_xxx"

# Set fallback value for all stages
sst secret set API_KEY "key-xxx" --fallback
```

```typescript
// sst.config.ts — link secrets like any resource
const dbUrl = new sst.Secret("DatabaseUrl");
const stripeKey = new sst.Secret("StripeSecretKey");

new sst.aws.Function("Api", {
  handler: "src/api.handler",
  link: [dbUrl, stripeKey],
});
```

```typescript
// Runtime — access via Resource
import { Resource } from "sst";
const connectionString = Resource.DatabaseUrl.value;
const stripe = new Stripe(Resource.StripeSecretKey.value);
```

**Why good:** Secrets are encrypted at rest in S3, per-stage isolation, accessed through the same `Resource.*` pattern as other links, no `.env` files to manage

---

## Global Helpers

```typescript
// $app — app context
const isProd = $app.stage === "production";
const appName = $app.name;

// $dev — boolean, true during sst dev
if ($dev) {
  // Skip expensive resources in dev mode
}

// $concat — join Output values (can't use template literals with Outputs)
const bucketArn = $concat("arn:aws:s3:::", bucket.name);

// $interpolate — template literal syntax for Outputs
const policy = $interpolate`arn:aws:s3:::${bucket.name}/*`;

// $resolve — await multiple Outputs
$resolve([bucket.name, table.name]).apply(([b, t]) => {
  console.log(`Bucket: ${b}, Table: ${t}`);
});

// $transform — set global defaults for a component type
$transform(sst.aws.Function, (args) => {
  args.runtime ??= "nodejs22.x";
  args.memory ??= "512 MB";
  args.architecture ??= "arm64";
});
```

**Why good:** Global helpers handle Pulumi Output resolution — you cannot use standard template literals or string concatenation with Output values. `$transform` sets defaults across all instances without repeating configuration.

```typescript
// BAD: Using template literals with Outputs
const arn = `arn:aws:s3:::${bucket.name}`; // ERROR: bucket.name is an Output, not a string
```

**Why bad:** Pulumi Outputs are not strings — template literals produce `[object Object]`. Must use `$concat()` or `$interpolate` instead.

---

## Dev Workflow

```bash
# 1. Start live development (personal stage)
sst dev

# 2. The multiplexer:
#    - Deploys infrastructure to your personal stage
#    - Proxies Lambda invocations to your local machine
#    - Starts frontend dev servers (Next.js, Vite, etc.)
#    - Creates VPC tunnel if needed

# 3. Make code changes — Lambda reloads in <10ms

# 4. When done, either:
#    a) Run sst dev again next time (stubs still deployed)
#    b) Deploy real code: sst deploy
```

### VS Code Debugging

Enable "Debug: Toggle Auto Attach" -> "Always" in VS Code, then start `sst dev` in a new terminal. Set breakpoints in your Lambda handlers — they'll hit when invoked.

### Detect Dev Mode in Handlers

```typescript
export async function handler(event: unknown) {
  if (process.env.SST_DEV) {
    // Local dev behavior (e.g., skip rate limiting, use local DB)
  }
}
```

# SST (Ion) — Deployment & DevOps Patterns

> Deployment, CI/CD, transforms, removal policies, VPC, containers, and frontend framework patterns. See [SKILL.md](../SKILL.md) for decision guidance.

**Related examples:**

- [Core Patterns](core.md) — sst.config.ts, resource linking, live dev, secrets
- [API & Data](api-data.md) — ApiGatewayV2, Dynamo, Bucket, Queue, Topic, Cron

---

## Multi-Stage Configuration

```typescript
/// <reference path="./.sst/platform/config.d.ts" />

export default $config({
  app(input) {
    return {
      name: "my-app",
      home: "aws",
      removal: input.stage === "production" ? "retain" : "remove",
      protect: input.stage === "production",
      providers: {
        aws: {
          region: "us-east-1",
          // Different AWS profile per stage (optional)
          ...(input.stage === "production" && { profile: "prod" }),
        },
      },
    };
  },
  async run() {
    const isProd = $app.stage === "production";
    const isStaging = $app.stage === "staging";

    const table = new sst.aws.Dynamo("Data", {
      fields: { pk: "string", sk: "string" },
      primaryIndex: { hashKey: "pk", rangeKey: "sk" },
      deletionProtection: isProd,
    });

    const api = new sst.aws.ApiGatewayV2("Api", {
      domain: isProd
        ? "api.example.com"
        : isStaging
          ? "api-staging.example.com"
          : undefined,
    });

    api.route("GET /", {
      handler: "src/index.handler",
      link: [table],
    });

    return { url: api.url };
  },
});
```

**Why good:** Stage-aware removal (retain prod data), stage-aware domain names, deletion protection only in production, TypeScript conditionals for stage logic

---

## Removal Policies

```typescript
app(input) {
  return {
    name: "my-app",
    home: "aws",
    // What happens when you run `sst remove`
    removal: input.stage === "production"
      ? "retain"      // Keep all resources (safe for production)
      : "remove",     // Delete everything (clean dev stages)
    // "retain-all" keeps everything including CloudWatch logs
  };
}
```

| Policy         | Behavior                                 | Use For                            |
| -------------- | ---------------------------------------- | ---------------------------------- |
| `"remove"`     | Deletes all resources                    | Dev stages, PR previews            |
| `"retain"`     | Keeps data resources (S3, DynamoDB, RDS) | Production                         |
| `"retain-all"` | Keeps everything including logs          | Production with audit requirements |

---

## Transforms — Per-Component

```typescript
// Customize underlying Lambda resource
new sst.aws.Function("Api", {
  handler: "src/api.handler",
  transform: {
    function: (args) => {
      // Enable X-Ray tracing (not exposed by SST)
      args.tracingConfig = { mode: "Active" };
    },
    role: (args) => {
      // Customize IAM role
      args.maxSessionDuration = 7200;
    },
  },
});

// Customize underlying API Gateway resource
new sst.aws.ApiGatewayV2("Api", {
  transform: {
    route: {
      handler: (args) => {
        // Set default memory for all route handlers
        args.memory ??= "2048 MB";
      },
    },
  },
});
```

**Why good:** `transform` modifies the underlying Pulumi resource properties without abandoning SST's abstractions — you get both SST's linking/permissions AND low-level customization

---

## Transforms — Global Defaults

```typescript
async run() {
  // Apply to ALL Functions in the app
  $transform(sst.aws.Function, (args) => {
    args.runtime ??= "nodejs22.x";
    args.architecture ??= "arm64";
    args.memory ??= "512 MB";
    args.timeout ??= "30 seconds";
  });

  // Apply to ALL Dynamo tables
  $transform(sst.aws.Dynamo, (args) => {
    args.deletionProtection ??= $app.stage === "production";
  });

  // Now every Function and Dynamo table inherits these defaults
  // unless explicitly overridden
  const api = new sst.aws.Function("Api", {
    handler: "src/api.handler",
    // memory: "512 MB" and architecture: "arm64" from $transform
  });
}
```

**Why good:** `$transform` sets defaults once instead of repeating on every component, `??=` only applies if not already set (overridable)

---

## VPC and Containers

```typescript
async run() {
  const vpc = new sst.aws.Vpc("AppVpc", {
    bastion: true, // EC2 bastion for SSH tunneling to private subnets
    nat: "managed", // NAT Gateway for private subnet internet access
  });

  const db = new sst.aws.Postgres("Database", {
    vpc,
    scaling: {
      min: "0.5 ACU",
      max: "4 ACU",
    },
  });

  const cluster = new sst.aws.Cluster("AppCluster", { vpc });

  cluster.addService("Api", {
    link: [db],
    scaling: { min: 1, max: 10 },
    image: { context: "./api" }, // Dockerfile in ./api
    dev: {
      command: "node --watch src/index.ts",
    },
  });

  // Lambda functions can also use VPC
  new sst.aws.Function("Migration", {
    handler: "src/migrate.handler",
    vpc,
    link: [db],
    timeout: "5 minutes",
  });
}
```

**Why good:** VPC with bastion for database access, Postgres with autoscaling, ECS service with auto-scaling, Lambda in VPC for migrations, all connected via resource linking

---

## Frontend Framework Deployments

### Next.js

```typescript
const web = new sst.aws.Nextjs("Web", {
  link: [api, table, bucket],
  domain: $app.stage === "production" ? "example.com" : undefined,
  environment: {
    // Public env vars use the framework's prefix (e.g., NEXT_PUBLIC_ for Next.js)
    PUBLIC_API_URL: api.url,
  },
});
```

### Remix

```typescript
const web = new sst.aws.Remix("Web", {
  link: [table],
  domain: "app.example.com",
});
```

### Astro

```typescript
const web = new sst.aws.Astro("Web", {
  link: [bucket],
  domain: "docs.example.com",
});
```

### Static Site

```typescript
const site = new sst.aws.StaticSite("Docs", {
  path: "./docs",
  domain: "docs.example.com",
  environment: {
    API_URL: api.url,
  },
});
```

**Key point:** Frontend `link` values are only accessible in server-side code (SSR, API routes, server loaders). Client-side code must use `environment` for public values.

---

## CI/CD with GitHub Actions

```yaml
# .github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main]

# Prevent concurrent deployments to the same stage
concurrency:
  group: deploy-${{ github.ref }}
  cancel-in-progress: false

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: "22"
          cache: npm

      - run: npm ci

      # OIDC auth (recommended over long-lived keys)
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/github-deploy
          aws-region: us-east-1

      - name: Deploy to production
        run: npx sst deploy --stage production
```

### PR Preview Environments

```yaml
# .github/workflows/preview.yml
name: Preview

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  preview:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "22"
          cache: npm
      - run: npm ci

      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/github-deploy
          aws-region: us-east-1

      - name: Deploy preview
        run: npx sst deploy --stage pr-${{ github.event.pull_request.number }}

  cleanup:
    runs-on: ubuntu-latest
    if: github.event.action == 'closed'
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "22"
          cache: npm
      - run: npm ci

      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/github-deploy
          aws-region: us-east-1

      - name: Remove preview
        run: npx sst remove --stage pr-${{ github.event.pull_request.number }}
```

**Why good:** OIDC authentication (no long-lived AWS keys), PR-based preview environments with automatic cleanup, concurrency group prevents race conditions

---

## Monorepo Structure

For larger projects, split infrastructure into an `infra/` directory:

```typescript
// sst.config.ts
/// <reference path="./.sst/platform/config.d.ts" />

export default $config({
  app(input) {
    return {
      name: "my-app",
      home: "aws",
      removal: input.stage === "production" ? "retain" : "remove",
    };
  },
  async run() {
    // Split infra into focused modules
    const { table, bucket } = await import("./infra/storage");
    const { api } = await import("./infra/api");
    const { web } = await import("./infra/web");

    return {
      apiUrl: api.url,
      webUrl: web.url,
    };
  },
});
```

```typescript
// infra/storage.ts
export const table = new sst.aws.Dynamo("Data", {
  fields: { pk: "string", sk: "string" },
  primaryIndex: { hashKey: "pk", rangeKey: "sk" },
});

export const bucket = new sst.aws.Bucket("Uploads");
```

```typescript
// infra/api.ts
import { table, bucket } from "./storage";

export const api = new sst.aws.ApiGatewayV2("Api");
api.route("GET /items", {
  handler: "src/items/list.handler",
  link: [table],
});
api.route("POST /upload", {
  handler: "src/upload.handler",
  link: [bucket],
});
```

**Why good:** `sst.config.ts` stays clean, infrastructure modules can import from each other, resources are co-located with their related config