Padrões SST (Ion)

O que Padrões SST (Ion) faz?

Guia Rápido: SST v3 (Ion) é infraestrutura como código TypeScript-first para AWS, alimentado por Pulumi/Terraform (não CDK/CloudFormation). Defina todo o seu app em sst.config.ts usando componentes de alto nível (sst.aws.Function, sst.aws.ApiGatewayV2, sst.aws.Bucket, sst.aws.Dynamo, etc.). Use vinculação de recursos (link: [bucket] + Resource.MyBucket.name) para acesso type-safe e com permissões entre componentes. Use sst dev para desenvolvimento Lambda ao vivo com recarregamentos abaixo de 10ms. Use $app.stage para isolar ambientes. Use transform para personalizar recursos Pulumi subjacentes.

---

<critical_requirements>

CRÍTICO: Antes de Usar Esta Skill

Todo código deve seguir as convenções do projeto no CLAUDE.md (kebab-case, exported names, ordenação de imports, import type, named constants)

(Você DEVE usar vinculação de recursos (link + Resource.*) para conectar componentes — NUNCA hardcode ARNs, table names ou bucket names)

(Você DEVE usar $app.stage para isolar ambientes — NUNCA compartilhe recursos entre estágios sem intenção explícita)

(Você DEVE usar sst dev para desenvolvimento local — ele fornece proxy Lambda ao vivo com recarregamentos abaixo de 10ms em recursos reais da AWS)

(Você DEVE usar sst secret set para segredos — NUNCA coloque segredos em sst.config.ts, arquivos .env commitados no git ou variáveis de ambiente)

(Você DEVE usar transform para personalizar recursos subjacentes — NUNCA recorra a recursos Pulumi brutos quando um componente SST existir)

</critical_requirements>

---

Exemplos

• Padrões Principais — estrutura sst.config.ts, Function, vinculação de recursos, globais $app, segredos, multi-estágio
• API & Dados — ApiGatewayV2, Dynamo, Bucket, Queue, Topic, Cron, autorização
• Deploy & DevOps — sst deploy, CI/CD, políticas de remoção, transforms, Vpc, Cluster, frameworks frontend
• Referência Rápida — comandos CLI, cheat sheet de componentes, helpers globais, constantes nomeadas

---

Detecção automática: 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 do sst, sst dev, sst deploy, sst remove, sst secret, $app.stage, $transform, $concat, $interpolate, vinculação de recursos, Lambda ao vivo, Ion

Quando usar:

• Definindo infraestrutura AWS em TypeScript com componentes de alto nível
• Implantando aplicações serverless (Lambda, API Gateway, DynamoDB, S3, SQS, SNS)
• Implantando apps full-stack (Next.js, Remix, Astro, SvelteKit, SolidStart na AWS)
• Configurando desenvolvimento Lambda ao vivo com recursos reais da AWS
• Gerenciando ambientes multi-estágio (dev, staging, production)
• Conectando componentes de infraestrutura com vinculação de recursos type-safe

Quando NÃO usar:

• Infraestrutura multi-cloud abrangendo muitos provedores (SST é focado em AWS com suporte limitado a Cloudflare)
• Codebases existentes de Terraform/Pulumi onde a abstração SST não agrega valor
• Projetos que precisam de deploys exclusivos com containers sem componentes serverless

Padrões principais cobertos:

• Estrutura sst.config.ts (funções app() + run())
• Vinculação de recursos: propriedade link + SDK Resource.*
• Desenvolvimento Lambda ao vivo com sst dev
• Componentes AWS: Function, ApiGatewayV2, Dynamo, Bucket, Queue, Topic, Cron
• Deploys frontend: Nextjs, Remix, Astro, StaticSite
• Isolamento multi-estágio com $app.stage
• Transforms para personalizar recursos Pulumi subjacentes
• Gerenciamento de segredos com sst secret
• Linkables personalizados com sst.Linkable e Linkable.wrap
• Helpers globais: $app, $dev, $concat, $interpolate, $resolve, $transform

---

Filosofia

SST v3 (Ion) substitui CDK/CloudFormation por Pulumi/Terraform para deploys dramaticamente mais rápidos e um modelo de programação mais simples. As ideias centrais:

1. Um arquivo de config — Todo o seu app é definido em sst.config.ts. Infraestrutura, frontends e funções são declarados juntos em TypeScript com loops, condicionais e funções.
2. Componentes sobre constructs — Componentes de alto nível sst.aws.* encapsulam boas práticas (IAM, logging, monitoramento). Use transform para acessar recursos subjacentes quando os defaults não forem suficientes.
3. Vinculação de recursos — O recurso matador. link: [bucket] automaticamente concede permissões IAM e injeta referências type-safe. Acesse via Resource.MyBucket.name em tempo de execução. Sem passagem manual de ARNs ou fiação de variáveis de ambiente.
4. Isolamento baseado em estágio — Cada desenvolvedor tem seu próprio estágio (sst dev cria um stack pessoal). $app.stage orienta a nomeação de recursos. Produção usa sst deploy --stage production.
5. Dev ao vivo contra AWS real — sst dev substitui funções Lambda por stubs que fazem proxy para sua máquina local. Mudanças recarregam em menos de 10ms. Sem emulação local — seu código roda contra DynamoDB, S3, SQS reais.

Quando usar SST:

• Aplicações serverless-first na AWS (Lambda, API Gateway, DynamoDB, S3, SQS, SNS)
• Apps full-stack que implantam frameworks frontend (Next.js, Remix, Astro) na AWS
• Times que querem infraestrutura TypeScript com mínimo boilerplate AWS
• Projetos que precisam de loops rápidos de desenvolvimento local contra recursos reais na nuvem

Quando NÃO usar SST:

• Infraestrutura multi-cloud além de AWS + Cloudflare (o suporte multi-cloud do SST é limitado)
• Cargas de trabalho exclusivas com containers sem componentes serverless (use Pulumi ou Terraform puro)
• Codebases existentes grandes de Terraform/Pulumi onde a abstração SST adiciona custo de migração

---

Padrões Principais

Padrão 1: Estrutura sst.config.ts

Todo app SST tem um único sst.config.ts com duas funções: app() para metadados e run() para recursos.

/// <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 };
  },
});

Por que é bom: app() lida com metadados e políticas específicas de estágio, run() define todos os recursos, removal: "retain" protege dados de produção, valores retornados se tornam outputs em .sst/outputs.json

Veja examples/core.md para config completa com multi-estágio, providers e padrões de proteção.

---

Padrão 2: Vinculação de Recursos

O recurso definidor do SST. Vincule recursos para conceder permissões e acesso type-safe automaticamente.

// Em 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],
});

// Em src/api.ts — código em tempo de execução
import { Resource } from "sst";
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";

const client = new DynamoDBClient({});
// Resource.Notes.name é o nome da tabela — type-safe, gerado automaticamente
console.log(Resource.Notes.name);

Por que é bom: Sem passagem manual de ARNs, permissões IAM concedidas automaticamente, acesso type-safe via sst-env.d.ts gerado, funciona em Functions, frontends e containers

Veja examples/core.md para padrões de vinculação incluindo linkables personalizados.

---

Padrão 3: Desenvolvimento Lambda ao Vivo

sst dev faz proxy de invocações Lambda para sua máquina local com ciclos de recarregamento abaixo de 10ms.

# Iniciar dev ao vivo — implanta infra, faz proxy de Lambda para máquina local
sst dev

# Abre multiplexador: implanta recursos, inicia frontends, faz tunnel VPC

// Detectar modo dev no código do handler
const isLocal = process.env.SST_DEV === "true";

Comportamento chave: Funções são substituídas por stubs que encaminham eventos via AppSync para sua máquina local. Seu código local roda como Workers Node.js. Mudanças recarregam instantaneamente — sem necessidade de redeploy.

Pegadinha: Interromper sst dev deixa stubs implantados. Invocações Lambda subsequentes irão expirar até que você execute sst dev novamente ou sst deploy para substituir stubs por código real.

Veja examples/core.md para workflow de dev e configuração de debugging.

---

Padrão 4: Componentes AWS

SST fornece componentes de alto nível para serviços AWS comuns. Cada um lida com IAM, logging e configuração automaticamente.

Componente	Serviço AWS	Caso de Uso
sst.aws.Function	Lambda	Funções serverless
sst.aws.ApiGatewayV2	API Gateway v2	APIs HTTP com rotas
sst.aws.Dynamo	DynamoDB	Banco NoSQL
sst.aws.Bucket	S3	Armazenamento de objetos
sst.aws.Queue	SQS	Filas de mensagens
sst.aws.Topic	SNS	Mensageria pub/sub
sst.aws.Cron	EventBridge	Tarefas agendadas
sst.aws.Vpc	VPC	Isolamento de rede
sst.aws.Cluster	ECS	Cargas de trabalho em containers
sst.aws.Postgres	RDS Postgres	Banco relacional
sst.aws.Nextjs	Lambda + CloudFront	Deploy Next.js
sst.aws.Remix	Lambda + CloudFront	Deploy Remix
sst.aws.Astro	Lambda + CloudFront	Deploy Astro
sst.aws.StaticSite	S3 + CloudFront	Hospedagem de site estático
sst.aws.Router	CloudFront	Roteamento de URL

Veja examples/api-data.md para padrões de API, banco, armazenamento, fila e cron.

---

Padrão 5: Gerenciamento de Segredos

Segredos são criptografados e armazenados no S3, injetados nos bundles de função no momento do deploy.

# Definir um segredo (solicita o valor)
sst secret set DATABASE_URL

# Definir um segredo com valor inline
sst secret set STRIPE_KEY sk_live_xxx

# Carregar segredos de um arquivo
sst secret load .env.production

# Listar todos os segredos
sst secret list

// Acessar segredos via vinculação de recursos
import { Resource } from "sst";
const stripeKey = Resource.StripeKey.value;

Pegadinha: Segredos são por estágio. Defina-os para cada estágio separadamente. Use --fallback para definir um padrão em todos os estágios.

Veja examples/core.md para segredos com padrão Linkable.

---

Padrão 6: Transforms

Personalize recursos Pulumi subjacentes quando os defaults do SST não forem suficientes.

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

// Transform global — aplica a TODOS os componentes de um tipo
$transform(sst.aws.Function, (args) => {
  args.environment ??= {};
  args.environment.variables ??= {};
  args.environment.variables.STAGE = $app.stage;
});

Por que é bom: Transforms permitem personalizar qualquer propriedade de recurso subjacente sem abandonar as abstrações do SST. Transforms globais definem defaults em todos os componentes.

Veja examples/deployment.md para padrões de transform.

---

Padrão 7: Ambientes Multi-Estágio

Cada estágio é um deployment totalmente isolado. Use $app.stage para configuração condicional.

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,
  });
}

# Estágio dev pessoal (padrão)
sst dev

# Deploy para staging
sst deploy --stage staging

# Deploy para produção
sst deploy --stage production

Veja examples/deployment.md para padrões multi-estágio com políticas de remoção.

---

<decision_framework>

Framework de Decisão

Escolhendo um Componente SST

O que você está construindo?
  |
  +-- API HTTP
  |     +-- Rotas simples com handlers Lambda --> sst.aws.ApiGatewayV2
  |     +-- Precisa de suporte WebSocket --> sst.aws.ApiGatewayWebSocket
  |     +-- Roteamento de URL / CDN --> sst.aws.Router
  |
  +-- Armazenamento de dados
  |     +-- Dados chave-valor / documento --> sst.aws.Dynamo
  |     +-- Dados relacionais com SQL --> sst.aws.Postgres
  |     +-- Armazenamento de arquivos/blobs --> sst.aws.Bucket
  |
  +-- Processamento assíncrono
  |     +-- Mensageria ponto-a-ponto --> sst.aws.Queue (SQS)
  |     +-- Fan-out para múltiplos assinantes --> sst.aws.Topic (SNS)
  |     +-- Tarefas agendadas --> sst.aws.Cron
  |
  +-- Computação
  |     +-- Função serverless --> sst.aws.Function
  |     +-- Carga de trabalho em container --> sst.aws.Cluster + sst.aws.Service
  |     +-- Job de background de longa duração --> sst.aws.Function (até 15min)
  |
  +-- Frontend 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 estático --> sst.aws.StaticSite

Quando Usar Transforms vs Pulumi Puro

Precisa definir uma propriedade em um componente SST?
  |
  +-- A propriedade existe nos argumentos do componente SST --> Use a propriedade SST diretamente
  |
  +-- A propriedade existe apenas no recurso AWS subjacente --> Use transform
  |
  +-- Precisa definir um default em TODAS as instâncias de um componente --> Use $transform()
  |
  +-- Nenhum componente SST existe para este serviço AWS --> Use recurso Pulumi puro
        +-- Precisa vinculá-lo? --> Use sst.Linkable.wrap() ou new sst.Linkable()

</decision_framework>

---