SST (Ion) Patterns

Was macht SST (Ion) Patterns?

Schnellübersicht: SST v3 (Ion) ist TypeScript-zentrierte Infrastructure-as-Code für AWS, basierend auf Pulumi/Terraform (nicht CDK/CloudFormation). Definiere deine gesamte Anwendung in sst.config.ts mit High-Level-Komponenten (sst.aws.Function, sst.aws.ApiGatewayV2, sst.aws.Bucket, sst.aws.Dynamo, usw.). Verwende Ressourcen-Linking (link: [bucket] + Resource.MyBucket.name) für typsicheren, berechtigungsbewussten Zugriff zwischen Komponenten. Verwende sst dev für Live-Lambda-Entwicklung mit Nachladezeiten unter 10 ms. Verwende $app.stage für Multi-Umgebungs-Isolierung. Verwende transform, um zugrunde liegende Pulumi-Ressourcen anzupassen.

---

<critical_requirements>

KRITISCH: Vor der Verwendung dieser Skill

Der gesamte Code muss den Projektkonventionen in CLAUDE.md folgen (Kebab-Case, benannte Exporte, Import-Reihenfolge, import type, benannte Konstanten)

(Du MUSST Ressourcen-Linking (link + Resource.*) verwenden, um Komponenten zu verbinden – NIEMALS ARNs, Tabellennamen oder Bucket-Namen hartcodieren)

(Du MUSST $app.stage für Umgebungsisolierung verwenden – NIEMALS Ressourcen ohne explizite Absicht über Stages hinweg teilen)

(Du MUSST sst dev für die lokale Entwicklung verwenden – es bietet Live-Lambda-Proxy mit Nachladezeiten unter 10 ms gegen reale AWS-Ressourcen)

(Du MUSST sst secret set für Geheimnisse verwenden – NIEMALS Geheimnisse in sst.config.ts, in Git eingecheckte .env-Dateien oder Umgebungsvariablen ablegen)

(Du MUSST transform verwenden, um zugrunde liegende Ressourcen anzupassen – NIEMALS auf rohe Pulumi-Ressourcen zurückgreifen, wenn eine SST-Komponente existiert)

</critical_requirements>

---

Beispiele

• Kernmuster – sst.config.ts-Struktur, Function, Ressourcen-Linking, $app-Globals, Geheimnisse, Multi-Stage
• API & Daten – ApiGatewayV2, Dynamo, Bucket, Queue, Topic, Cron, Autorisierung
• Bereitstellung & DevOps – sst deploy, CI/CD, Löschrichtlinien, Transforms, Vpc, Cluster, Frontend-Frameworks
• Kurzreferenz – CLI-Befehle, Komponenten-Spickzettel, globale Helfer, benannte Konstanten

---

Auto-Erkennung: 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, Ressourcen-Linking, Live Lambda, Ion

Wann verwenden:

• Definieren von AWS-Infrastruktur in TypeScript mit High-Level-Komponenten
• Bereitstellen serverloser Anwendungen (Lambda, API Gateway, DynamoDB, S3, SQS, SNS)
• Bereitstellen von Full-Stack-Apps (Next.js, Remix, Astro, SvelteKit, SolidStart auf AWS)
• Einrichten der Live-Lambda-Entwicklung mit realen AWS-Ressourcen
• Verwalten von Multi-Stage-Umgebungen (Dev, Staging, Produktion)
• Verbinden von Infrastrukturkomponenten mit typsicherem Ressourcen-Linking

Wann NICHT verwenden:

• Multi-Cloud-Infrastruktur, die viele Anbieter umspannt (SST ist AWS-fokussiert mit begrenzter Cloudflare-Unterstützung)
• Vorhandene Terraform-/Pulumi-Codebasen, bei denen die SST-Abstraktion keinen Mehrwert bietet
• Projekte, die reine Container-Bereitstellungen ohne serverlose Komponenten benötigen

Wichtigste abgedeckte Muster:

• sst.config.ts-Struktur (app() + run()-Funktionen)
• Ressourcen-Linking: link-Eigenschaft + Resource.*-SDK
• Live-Lambda-Entwicklung mit sst dev
• AWS-Komponenten: Function, ApiGatewayV2, Dynamo, Bucket, Queue, Topic, Cron
• Frontend-Bereitstellungen: Nextjs, Remix, Astro, StaticSite
• Multi-Stage-Isolierung mit $app.stage
• Transforms zum Anpassen zugrunde liegender Pulumi-Ressourcen
• Geheimnisverwaltung mit sst secret
• Benutzerdefinierte Linkables mit sst.Linkable und Linkable.wrap
• Globale Helfer: $app, $dev, $concat, $interpolate, $resolve, $transform

---

Philosophie

SST v3 (Ion) ersetzt CDK/CloudFormation durch Pulumi/Terraform für deutlich schnellere Bereitstellungen und ein einfacheres Programmiermodell. Die Kernideen:

1. Eine Konfigurationsdatei – Deine gesamte Anwendung wird in sst.config.ts definiert. Infrastruktur, Frontends und Funktionen werden alle zusammen in TypeScript mit Schleifen, Bedingungen und Funktionen deklariert.
2. Komponenten statt Konstrukte – High-Level-sst.aws.*-Komponenten kapseln Best Practices (IAM, Logging, Monitoring). Verwende transform, um in zugrunde liegende Ressourcen zu greifen, wenn die Standardeinstellungen nicht ausreichen.
3. Ressourcen-Linking – Die Killer-Funktion. link: [bucket] gewährt automatisch IAM-Berechtigungen und injiziert typsichere Referenzen. Zugriff über Resource.MyBucket.name zur Laufzeit. Kein manuelles Übergeben von ARNs oder Verkabeln von Umgebungsvariablen.
4. Bühnenbasierte Isolierung – Jeder Entwickler bekommt seine eigene Stage (sst dev erstellt einen persönlichen Stack). $app.stage steuert die Ressourcenbenennung. Die Produktion verwendet sst deploy --stage production.
5. Live-Entwicklung gegen echte AWS – sst dev ersetzt Lambda-Funktionen durch Stubs, die zu deinem lokalen Rechner proxen. Änderungen laden in unter 10 ms neu. Keine lokale Emulation – dein Code läuft gegen echte DynamoDB, S3, SQS.

Wann SST verwenden:

• Serverlose Anwendungen auf AWS (Lambda, API Gateway, DynamoDB, S3, SQS, SNS)
• Full-Stack-Apps, die Frontend-Frameworks (Next.js, Remix, Astro) auf AWS bereitstellen
• Teams, die TypeScript-Infrastruktur mit minimalem AWS-Boilerplate möchten
• Projekte, die schnelle lokale Entwicklungszyklen gegen echte Cloud-Ressourcen benötigen

Wann SST NICHT verwenden:

• Multi-Cloud-Infrastruktur über AWS + Cloudflare hinaus (SSTs Multi-Cloud-Unterstützung ist begrenzt)
• Reine Container-Workloads ohne serverlose Komponenten (verwende rohes Pulumi oder Terraform)
• Vorhandene große Terraform-/Pulumi-Codebasen, bei denen die SST-Abstraktion Migrationskosten verursacht

---

Kernmuster

Muster 1: sst.config.ts-Struktur

Jede SST-App hat eine einzelne sst.config.ts mit zwei Funktionen: app() für Metadaten und run() für Ressourcen.

/// <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() {
    const bucket = new sst.aws.Bucket("Uploads");
    const api = new sst.aws.Function("Api", {
      handler: "src/api.handler",
      link: [bucket],
    });
    return { apiUrl: api.url };
  },
});

Warum gut: app() behandelt Metadaten und Stage-spezifische Richtlinien, run() definiert alle Ressourcen, removal: "retain" schützt Produktionsdaten, zurückgegebene Werte werden zu Ausgaben in .sst/outputs.json

Vollständige Konfiguration mit Multi-Stage, Providers und Protect-Mustern siehe examples/core.md.

---

Muster 2: Ressourcen-Linking

Das SST-Defining-Feature. Verknüpfe Ressourcen, um automatisch Berechtigungen und typsicheren Zugriff zu gewähren.

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

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

// In src/api.ts – Laufzeitcode
import { Resource } from "sst";
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";

const client = new DynamoDBClient({});
// Resource.Notes.name ist der Tabellenname – typsicher, automatisch generiert
console.log(Resource.Notes.name);

Warum gut: Kein manuelles Übergeben von ARNs, IAM-Berechtigungen werden automatisch gewährt, typsicherer Zugriff über generierte sst-env.d.ts, funktioniert über Functions, Frontends und Container hinweg

Linking-Muster einschließlich benutzerdefinierter Linkables siehe examples/core.md.

---

Muster 3: Live-Lambda-Entwicklung

sst dev proxt Lambda-Aufrufe zu deinem lokalen Rechner für Nachladezyklen unter 10 ms.

# Live-Entwicklung starten – stellt Infrastruktur bereit, proxt Lambda zu lokalem Rechner
sst dev

# Öffnet Multiplexer: stellt Ressourcen bereit, startet Frontends, tunnelt VPC

// Dev-Modus im Handler-Code erkennen
const isLocal = process.env.SST_DEV === "true";

Schlüsselverhalten: Funktionen werden durch Stubs ersetzt, die Ereignisse über AppSync an Ihren lokalen Rechner weiterleiten. Ihr lokaler Code wird als Node.js-Worker ausgeführt. Änderungen werden sofort neu geladen – keine erneute Bereitstellung erforderlich.

Achtung: Das Beenden von sst dev hinterlässt bereitgestellte Stubs. Nachfolgende Lambda-Aufrufe laufen in ein Timeout, bis du sst dev erneut ausführst oder sst deploy ausführst, um die Stubs durch echten Code zu ersetzen.

Siehe examples/core.md für den Entwicklungsablauf und die Debugging-Einrichtung.

---

Muster 4: AWS-Komponenten

SST bietet High-Level-Komponenten für gängige AWS-Dienste. Jede verwaltet IAM, Logging und Konfiguration automatisch.

Komponente	AWS-Dienst	Anwendungsfall
sst.aws.Function	Lambda	Serverlose Funktionen
sst.aws.ApiGatewayV2	API Gateway v2	HTTP-APIs mit Routen
sst.aws.Dynamo	DynamoDB	NoSQL-Datenbank
sst.aws.Bucket	S3	Objektspeicher
sst.aws.Queue	SQS	Nachrichtenwarteschlangen
sst.aws.Topic	SNS	Pub/Sub-Messaging
sst.aws.Cron	EventBridge	Zeitgesteuerte Aufgaben
sst.aws.Vpc	VPC	Netzwerkisolation
sst.aws.Cluster	ECS	Container-Workloads
sst.aws.Postgres	RDS Postgres	Relationale Datenbank
sst.aws.Nextjs	Lambda + CloudFront	Next.js-Bereitstellung
sst.aws.Remix	Lambda + CloudFront	Remix-Bereitstellung
sst.aws.Astro	Lambda + CloudFront	Astro-Bereitstellung
sst.aws.StaticSite	S3 + CloudFront	Statisches Site-Hosting
sst.aws.Router	CloudFront	URL-Routing

Siehe examples/api-data.md für API-, Datenbank-, Speicher-, Warteschlangen- und Cron-Muster.

---

Muster 5: Geheimnisverwaltung

Geheimnisse werden verschlüsselt in S3 gespeichert und zur Bereitstellungszeit in Funktionspakete injiziert.

# Ein Geheimnis setzen (fordert zur Eingabe auf)
sst secret set DATABASE_URL

# Ein Geheimnis mit Wert inline setzen
sst secret set STRIPE_KEY sk_live_xxx

# Geheimnisse aus einer Datei laden
sst secret load .env.production

# Alle Geheimnisse auflisten
sst secret list

// Zugriff auf Geheimnisse über Ressourcen-Linking
import { Resource } from "sst";
const stripeKey = Resource.StripeKey.value;

Achtung: Geheimnisse sind Stage-spezifisch. Setze sie für jede Stage separat. Verwende --fallback, um einen Standardwert für alle Stages festzulegen.

Siehe examples/core.md für Geheimnisse mit dem Linkable-Muster.

---

Muster 6: Transforms

Passe zugrunde liegende Pulumi-Ressourcen an, wenn die SST-Standardeinstellungen nicht ausreichen.

// Pro-Komponenten-Transform
new sst.aws.Function("Api", {
  handler: "src/api.handler",
  transform: {
    function: (args) => {
      args.tracingConfig = { mode: "Active" };
    },
  },
});

// Globaler Transform – gilt für ALLE Komponenten eines Typs
$transform(sst.aws.Function, (args) => {
  args.environment ??= {};
  args.environment.variables ??= {};
  args.environment.variables.STAGE = $app.stage;
});

Warum gut: Transforms ermöglichen es dir, jede zugrunde liegende Ressourceneigenschaft anzupassen, ohne SSTs Abstraktionen aufzugeben. Globale Transforms setzen Standardwerte für alle Komponenten.

Transform-Muster siehe examples/deployment.md.

---

Muster 7: Multi-Stage-Umgebungen

Jede Stage ist eine vollständig isolierte Bereitstellung. Verwende $app.stage für bedingte Konfiguration.

async run() {
  const isProd = $app.stage === "production";

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

# Persönliche Dev-Stage (Standard)
sst dev

# Nach Staging bereitstellen
sst deploy --stage staging

# In Produktion bereitstellen
sst deploy --stage production

Siehe examples/deployment.md für Multi-Stage-Muster mit Löschrichtlinien.

---

<decision_framework>

Entscheidungsrahmen

Auswählen einer SST-Komponente

Was baust du?
  |
  +-- HTTP-API
  |     +-- Einfache Routen mit Lambda-Handlern --> sst.aws.ApiGatewayV2
  |     +-- WebSocket-Unterstützung benötigt --> sst.aws.ApiGatewayWebSocket
  |     +-- URL-Routing / CDN --> sst.aws.Router
  |
  +-- Datenspeicher
  |     +-- Schlüssel-Wert / Dokumentendaten --> sst.aws.Dynamo
  |     +-- Relationale Daten mit SQL --> sst.aws.Postgres
  |     +-- Datei-/Blob-Speicher --> sst.aws.Bucket
  |
  +-- Asynchrone Verarbeitung
  |     +-- Punkt-zu-Punkt-Messaging --> sst.aws.Queue (SQS)
  |     +-- Fan-Out an mehrere Abonnenten --> sst.aws.Topic (SNS)
  |     +-- Zeitgesteuerte Aufgaben --> sst.aws.Cron
  |
  +-- Compute
  |     +-- Serverlose Funktion --> sst.aws.Function
  |     +-- Container-Workload --> sst.aws.Cluster + sst.aws.Service
  |     +-- Langlaufender Hintergrundjob --> sst.aws.Function (bis zu 15 Min.)
  |
  +-- Full-Stack-Frontend
        +-- Next.js --> sst.aws.Nextjs
        +-- Remix --> sst.aws.Remix
        +-- Astro --> sst.aws.Astro
        +-- SvelteKit --> sst.aws.SvelteKit
        +-- SolidStart --> sst.aws.SolidStart
        +-- Statisches HTML/JS --> sst.aws.StaticSite

Wann Transforms vs. Rohes Pulumi verwendet werden

Muss eine Eigenschaft einer SST-Komponente gesetzt werden?
  |
  +-- Eigenschaft existiert in den SST-Komponentenargumenten --> Verwende die SST-Eigenschaft direkt
  |
  +-- Eigenschaft existiert nur in der zugrunde liegenden AWS-Ressource --> Verwende transform
  |
  +-- Muss ein Standard für ALLE Instanzen einer Komponente gesetzt werden --> Verwende $transform()
  |
  +-- Für diesen AWS-Dienst existiert keine SST-Komponente --> Verwende rohe Pulumi-Ressource
        +-- Muss es verlinkt werden? --> Verwende sst.Linkable.wrap() oder new sst.Linkable()

</decision_framework>

---

<red_flags

…

[Gekürzt für die Übersetzung]