Modèles SST (Ion)
Guide rapide : SST v3 (Ion) est une infrastructure as code TypeScript-first pour AWS, propulsée par Pulumi/Terraform (et non CDK/CloudFormation). Définissez l'intégralité de votre application dans
sst.config.tsà l'aide de composants de haut niveau (sst.aws.Function,sst.aws.ApiGatewayV2,sst.aws.Bucket,sst.aws.Dynamo, etc.). Utilisez la liaison de ressources (link: [bucket]+Resource.MyBucket.name) pour un accès type-safe et conscient des permissions entre les composants. Utilisezsst devpour le développement Lambda en direct avec des rechargements inférieurs à 10 ms. Utilisez$app.stagepour l'isolation multi-environnement. Utiliseztransformpour personnaliser les ressources Pulumi sous-jacentes.
<exigences_critiques>
CRITIQUE : Avant d'utiliser ce skill
Tout le code doit suivre les conventions du projet dans CLAUDE.md (kebab-case, exports nommés, ordre des imports,
import type, constantes nommées)
(Vous DEVEZ utiliser la liaison de ressources (link + Resource.*) pour connecter les composants — ne codez JAMAIS en dur les ARN, les noms de tables ou les noms de buckets)
(Vous DEVEZ utiliser $app.stage pour l'isolation des environnements — ne partagez JAMAIS les ressources entre les étapes sans intention explicite)
(Vous DEVEZ utiliser sst dev pour le développement local — il fournit un proxy Lambda en direct avec des rechargements inférieurs à 10 ms sur des ressources AWS réelles)
(Vous DEVEZ utiliser sst secret set pour les secrets — ne mettez JAMAIS les secrets dans sst.config.ts, les fichiers .env commités dans git, ou les variables d'environnement)
(Vous DEVEZ utiliser transform pour personnaliser les ressources sous-jacentes — n'utilisez JAMAIS de ressources Pulumi brutes lorsqu'un composant SST existe)
</exigences_critiques>
Exemples
- Modèles de base — Structure sst.config.ts, Function, liaison de ressources, variables globales $app, secrets, multi-étape
- API et Données — ApiGatewayV2, Dynamo, Bucket, Queue, Topic, Cron, autorisation
- Déploiement et DevOps — sst deploy, CI/CD, politiques de suppression, transformations, Vpc, Cluster, frameworks front-end
- Référence rapide — Commandes CLI, aide-mémoire des composants, assistants globaux, constantes nommées
Détection automatique : 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 depuis sst, sst dev, sst deploy, sst remove, sst secret, $app.stage, $transform, $concat, $interpolate, liaison de ressources, Lambda en direct, Ion
Quand utiliser :
- Définir une infrastructure AWS en TypeScript avec des composants de haut niveau
- Déployer des applications sans serveur (Lambda, API Gateway, DynamoDB, S3, SQS, SNS)
- Déployer des applications full-stack (Next.js, Remix, Astro, SvelteKit, SolidStart sur AWS)
- Mettre en place un développement Lambda en direct avec des ressources AWS réelles
- Gérer des environnements multi-étapes (dev, staging, production)
- Connecter des composants d'infrastructure avec une liaison de ressources type-safe
Quand NE PAS utiliser :
- Infrastructure multi-cloud couvrant plusieurs fournisseurs (SST est principalement axé sur AWS avec un support limité de Cloudflare)
- Codebases Terraform/Pulumi existantes où l'abstraction SST n'apporte aucune valeur ajoutée
- Projets nécessitant des déploiements uniquement en conteneur sans composants sans serveur
Modèles clés couverts :
- Structure de
sst.config.ts(fonctionsapp()+run()) - Liaison de ressources : propriété
link+ SDKResource.* - Développement Lambda en direct avec
sst dev - Composants AWS : Function, ApiGatewayV2, Dynamo, Bucket, Queue, Topic, Cron
- Déploiements front-end : Nextjs, Remix, Astro, StaticSite
- Isolation multi-étape avec
$app.stage - Transformations pour personnaliser les ressources Pulumi sous-jacentes
- Gestion des secrets avec
sst secret - Liaisons personnalisables avec
sst.LinkableetLinkable.wrap - Assistants globaux :
$app,$dev,$concat,$interpolate,$resolve,$transform
Philosophie
SST v3 (Ion) remplace CDK/CloudFormation par Pulumi/Terraform pour des déploiements considérablement plus rapides et un modèle de programmation plus simple. Les idées centrales :
- Un seul fichier de configuration — Votre application entière est définie dans
sst.config.ts. Infrastructure, frontaux et fonctions sont tous déclarés ensemble en TypeScript avec des boucles, des conditionnelles et des fonctions. - Des composants plutôt que des constructs — Les composants de haut niveau
sst.aws.*encapsulent les meilleures pratiques (IAM, journalisation, surveillance). Utiliseztransformpour accéder aux ressources sous-jacentes lorsque les valeurs par défaut ne suffisent pas. - Liaison de ressources — La fonctionnalité phare.
link: [bucket]accorde automatiquement les permissions IAM et injecte des références type-safe. Accédez-y viaResource.MyBucket.nameà l'exécution. Plus besoin de passer manuellement les ARN ou de câbler les variables d'environnement. - Isolation par étape — Chaque développeur a sa propre étape (
sst devcrée une pile personnelle).$app.stagepilote le nommage des ressources. La production utilisesst deploy --stage production. - Développement en direct sur AWS réel —
sst devremplace les fonctions Lambda par des stubs qui font un proxy vers votre machine locale. Les modifications se rechargent en moins de 10 ms. Pas d'émulation locale — votre code s'exécute sur DynamoDB, S3, SQS réels.
Quand utiliser SST :
- Applications principalement sans serveur sur AWS (Lambda, API Gateway, DynamoDB, S3, SQS, SNS)
- Applications full-stack déployant des frameworks front-end (Next.js, Remix, Astro) sur AWS
- Équipes souhaitant une infrastructure TypeScript avec un minimum de code passe-partout AWS
- Projets nécessitant des boucles de développement local rapides sur des ressources cloud réelles
Quand NE PAS utiliser SST :
- Infrastructure multi-cloud au-delà d'AWS + Cloudflare (le support multi-cloud de SST est limité)
- Charges de travail uniquement en conteneur sans composants sans serveur (utilisez Pulumi ou Terraform bruts)
- Grandes codebases Terraform/Pulumi existantes où l'abstraction SST ajoute un coût de migration
<modèles>
Modèles de base
Modèle 1 : Structure sst.config.ts
Chaque application SST a un seul fichier sst.config.ts avec deux fonctions : app() pour les métadonnées et run() pour les ressources.
/// <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 };
},
});
Pourquoi c'est bien : app() gère les métadonnées et les politiques spécifiques à l'étape, run() définit toutes les ressources, removal: "retain" protège les données de production, les valeurs retournées deviennent des sorties dans .sst/outputs.json.
Voir examples/core.md pour une configuration complète avec multi-étape, providers et modèles de protection.
Modèle 2 : Liaison de ressources
La fonctionnalité phare de SST. Liez les ressources pour accorder automatiquement les permissions et l'accès type-safe.
// Dans 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],
});
// Dans src/api.ts — code d'exécution
import { Resource } from "sst";
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
const client = new DynamoDBClient({});
// Resource.Notes.name est le nom de la table — type-safe, généré automatiquement
console.log(Resource.Notes.name);
Pourquoi c'est bien : Pas de passage manuel d'ARN, permissions IAM accordées automatiquement, accès type-safe via sst-env.d.ts généré, fonctionne avec Functions, frontaux et conteneurs.
Voir examples/core.md pour les modèles de liaison, y compris les liaisons personnalisables.
Modèle 3 : Développement Lambda en direct
sst dev fait un proxy des invocations Lambda vers votre machine locale pour des cycles de rechargement inférieurs à 10 ms.
# Démarrer le développement en direct — déploie l'infrastructure, fait un proxy Lambda vers la machine locale
sst dev
# Ouvre le multiplexeur : déploie les ressources, démarre les frontaux, tunnel VPC
// Détecter le mode dev dans le code du handler
const isLocal = process.env.SST_DEV === "true";
Comportement clé : Les fonctions sont remplacées par des stubs qui transfèrent les événements via AppSync vers votre machine locale. Votre code local s'exécute en tant que Workers Node.js. Les modifications se rechargent instantanément — pas besoin de redéployer.
Piège : L'arrêt de sst dev laisse les stubs déployés. Les invocations Lambda ultérieures expireront jusqu'à ce que vous exécutiez sst dev à nouveau ou sst deploy pour remplacer les stubs par du code réel.
Voir examples/core.md pour le flux de travail de développement et la configuration de débogage.
Modèle 4 : Composants AWS
SST fournit des composants de haut niveau pour les services AWS courants. Chacun gère automatiquement IAM, la journalisation et la configuration.
| Composant | Service AWS | Cas d'utilisation |
|---|---|---|
sst.aws.Function | Lambda | Fonctions sans serveur |
sst.aws.ApiGatewayV2 | API Gateway v2 | API HTTP avec routes |
sst.aws.Dynamo | DynamoDB | Base de données NoSQL |
sst.aws.Bucket | S3 | Stockage d'objets |
sst.aws.Queue | SQS | Files d'attente de messages |
sst.aws.Topic | SNS | Messagerie Pub/Sub |
sst.aws.Cron | EventBridge | Tâches planifiées |
sst.aws.Vpc | VPC | Isolation réseau |
sst.aws.Cluster | ECS | Charges de travail conteneur |
sst.aws.Postgres | RDS Postgres | Base de données relationnelle |
sst.aws.Nextjs | Lambda + CloudFront | Déploiement Next.js |
sst.aws.Remix | Lambda + CloudFront | Déploiement Remix |
sst.aws.Astro | Lambda + CloudFront | Déploiement Astro |
sst.aws.StaticSite | S3 + CloudFront | Hébergement de site statique |
sst.aws.Router | CloudFront | Routage d'URL |
Voir examples/api-data.md pour les modèles d'API, base de données, stockage, file d'attente et cron.
Modèle 5 : Gestion des secrets
Les secrets sont chiffrés et stockés dans S3, injectés dans les bundles de fonctions au moment du déploiement.
# Définir un secret (demande la valeur)
sst secret set DATABASE_URL
# Définir un secret avec la valeur en ligne
sst secret set STRIPE_KEY sk_live_xxx
# Charger les secrets depuis un fichier
sst secret load .env.production
# Lister tous les secrets
sst secret list
// Accéder aux secrets via la liaison de ressources
import { Resource } from "sst";
const stripeKey = Resource.StripeKey.value;
Piège : Les secrets sont par étape. Définissez-les pour chaque étape séparément. Utilisez --fallback pour définir une valeur par défaut pour toutes les étapes.
Voir examples/core.md pour les secrets avec le modèle Linkable.
Modèle 6 : Transformations
Personnalisez les ressources Pulumi sous-jacentes lorsque les valeurs par défaut de SST ne suffisent pas.
// Transformation par composant
new sst.aws.Function("Api", {
handler: "src/api.handler",
transform: {
function: (args) => {
args.tracingConfig = { mode: "Active" };
},
},
});
// Transformation globale — s'applique à TOUS les composants d'un type
$transform(sst.aws.Function, (args) => {
args.environment ??= {};
args.environment.variables ??= {};
args.environment.variables.STAGE = $app.stage;
});
Pourquoi c'est bien : Les transformations vous permettent de personnaliser n'importe quelle propriété de ressource sous-jacente sans abandonner les abstractions de SST. Les transformations globales définissent des valeurs par défaut pour tous les composants.
Voir examples/deployment.md pour les modèles de transformation.
Modèle 7 : Environnements multi-étapes
Chaque étape est un déploiement totalement isolé. Utilisez $app.stage pour une configuration conditionnelle.
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,
});
}
# Étape de développement personnelle (par défaut)
sst dev
# Déployer sur staging
sst deploy --stage staging
# Déployer sur production
sst deploy --stage production
Voir examples/deployment.md pour les modèles multi-étapes avec politiques de suppression.
</modèles>
<cadre_décisionnel>
Cadre décisionnel
Choisir un composant SST
Que construisez-vous ?
|
+-- API HTTP
| +-- Routes simples avec handlers Lambda --> sst.aws.ApiGatewayV2
| +-- Besoin de support WebSocket --> sst.aws.ApiGatewayWebSocket
| +-- Routage d'URL / CDN --> sst.aws.Router
|
+-- Stockage de données
| +-- Données clé-valeur / document --> sst.aws.Dynamo
| +-- Données relationnelles avec SQL --> sst.aws.Postgres
| +-- Stockage de fichiers / blobs --> sst.aws.Bucket
|
+-- Traitement asynchrone
| +-- Messagerie point-à-point --> sst.aws.Queue (SQS)
| +-- Diffusion vers plusieurs abonnés --> sst.aws.Topic (SNS)
| +-- Tâches planifiées --> sst.aws.Cron
|
+-- Calcul
| +-- Fonction sans serveur --> sst.aws.Function
| +-- Charge de travail conteneur --> sst.aws.Cluster + sst.aws.Service
| +-- Tâche d'arrière-plan de longue durée --> sst.aws.Function (jusqu'à 15min)
|
+-- Front-end full-stack
+-- Next.js --> sst.aws.Nextjs
+-- Remix --> sst.aws.Remix
+-- Astro --> sst.aws.Astro
+-- SvelteKit --> sst.aws.SvelteKit
+-- SolidStart --> sst.aws.SolidStart
+-- HTML/JS statique --> sst.aws.StaticSite
Quand utiliser les transformations vs Pulumi brut
Besoin de définir une propriété sur un composant SST ?
|
+-- La propriété existe dans les arguments du composant SST --> Utilisez directement la propriété SST
|
+-- La propriété existe uniquement sur la ressource AWS sous-jacente --> Utilisez transform
|
+-- Besoin de définir une valeur par défaut pour TOUTES les instances d'un composant --> Utilisez $transform()
|
+-- Aucun composant SST n'existe pour ce service AWS --> Utilisez une ressource Pulumi brute
+-- Besoin de la lier ? --> Utilisez sst.Linkable.wrap() ou new sst.Linkable()
</cadre_décisionnel>
<drapeaux_rouges
…
[tronqué pour la traduction]