# GraphQL Subscriptions: Guia Passo a Passo Prático

> GraphQL Subscriptions são um recurso do GraphQL que mantém uma conexão persistente entre cliente e servidor para entregar dados em tempo real via WebSocket, geralmente usando pubsub para publicar eventos. A implementação exige configurar o servidor com suporte a WebSocket, escolher um pubsub adequado e conectar o cliente com transporte compatível.

*Digitorack · Apps e Software · 17 de setembro de 2026 · Letícia Sampaio Khoury*

Implementar GraphQL subscriptions assusta menos do que parece. Neste guia passo a passo, mostro como configurar o servidor, escolher o pubsub certo e conectar o cliente, com os erros que eu mesmo cometi no caminho.

GraphQL subscriptions resolvem um problema específico: entregar dados atualizados sem o cliente ficar perguntando de novo. Se você já tem um servidor GraphQL rodando, o caminho é curto. Antes de começar, garanta Node.js instalado, um servidor GraphQL funcional (Apollo Server ou similar) e noções básicas de schema. O resultado esperado ao final: um cliente recebendo mensagens em tempo real via WebSocket.

## Passo 1: Defina a subscription no schema

No seu schema, adicione um tipo Subscription com o evento que você quer transmitir. Algo como postAdded: Post. O erro comum aqui é esquecer que subscriptions não retornam listas: elas emitem um evento por vez. Se você precisa de vários itens, o cliente acumula.

## Passo 2: Configure o pubsub no servidor

Instale o pacote graphql-subscriptions (disponível no npm, conforme o registro do Wikidata) e crie uma instância do PubSub. No resolver da mutation, publique o evento; no resolver da subscription, use pubsub.asyncIterator. A dica que economiza horas: não use o PubSub em memória em produção com múltiplas instâncias. Ele não compartilha estado entre processos. Para isso, o caminho é Redis ou outro backend externo.

## Passo 3: Conecte o cliente via WebSocket

No cliente, troque o link HTTP por um link WebSocket (graphql-ws é a opção mais atual). Assine a operação e trate reconexão. Erro comum: esquecer de fechar a subscription ao desmontar o componente. Isso vaza conexão e derruba o servidor em pouco tempo.

## Checklist rápido

- Tipo Subscription definido no schema
- PubSub configurado e publicado na mutation
- Resolver da subscription usando asyncIterator
- Cliente com link WebSocket ativo
- Cleanup da subscription no unmount

## FAQ

### Preciso de WebSocket para GraphQL subscriptions?

Na prática, sim. O protocolo padrão usa WebSocket para manter a conexão aberta. Existem alternativas com SSE, mas o suporte é menos uniforme entre bibliotecas e servidores.

### Qual a diferença entre subscription e query?

Query busca dados uma vez. Subscription mantém um canal aberto e envia novos dados quando o evento ocorre. É push, não pull.

### Posso usar subscriptions em produção com múltiplos servidores?

Sim, mas não com PubSub em memória. Use Redis ou outro broker para que todos os processos recebam os eventos.

### O que é o pacote graphql-subscriptions?

É uma biblioteca Node.js que conecta o GraphQL a um sistema pubsub, permitindo implementar subscriptions sem escrever a camada de eventos do zero.

### Subscriptions funcionam com Apollo Client?

Funcionam, mas você precisa configurar um link WebSocket separado do link HTTP. Sem isso, a subscription simplesmente não conecta.

---

Fonte (canonical): https://digitorack.com.br/apps-e-software/graphql-subscriptions-guia-passo-a-passo-pratico/