Exemplos

O Spraxium inclui um conjunto completo de aplicações reais e executáveis em github.com/spraxium/spraxium/tree/main/apps. Atualmente, esses exemplos estão alinhados com as APIs atuais, incluindo builders assíncronos de componentes, padrões modernos de interação e arquitetura mais preparada para produção.

Esta página ajuda você a escolher o melhor ponto de partida para o seu objetivo e, em seguida, mostra um fluxo prático para executar, inspecionar e modificar os exemplos com segurança.

Mapa de apps

Atualmente, o Spraxium possui 13 apps oficiais de exemplo:

1. components-bot
2. context-menu-bot
3. dynamic-bot
4. guard-bot
5. http-bot
6. i18n-bot
7. i18n-components-bot
8. modal-bot
9. sandbox
10. schedule-bot
11. signal-bot
12. slash-bot
13. webhook-bot

upgrade-test-bot foi removido intencionalmente e não faz parte do conjunto de apps do modelo atual.

O que cada app ensina

1) slash-bot

Use primeiro se você quer a entrada mais limpa possível.

Você aprende:

• Registro e execução de slash commands.
• Organização de handlers e módulos com baixa complexidade inicial.
• Fluxo base de comandos antes de adicionar infraestrutura avançada.

2) context-menu-bot

Use quando seu fluxo começa por ações de contexto (usuário/mensagem), e não por slash command.

Você aprende:

• Comandos de contexto para usuário e mensagem.
• Padrões de defer e resposta para evitar timeout de interação.
• Composição de guards e services ao redor de handlers.

3) guard-bot

Use para entender camadas de controle de acesso e políticas.

Você aprende:

• Composição de guards para cargo, permissão e condição.
• Reuso de validações de segurança em módulo/handler.
• Padrões para tirar regra de autorização do código de negócio.

4) components-bot

Use quando você precisa de botões/select menus com fluxos mais ricos.

Você aprende:

• Uso de Component V2 com builders orientados a await.
• Fluxos de interação em múltiplas etapas.
• Mapeamento de interações de componente para handlers tipados.

5) dynamic-bot

Use quando dados precisam viajar dentro da interação de componentes.

Você aprende:

• Estratégias de identidade/payload dinâmico.
• Tratamento seguro de estado sem parsing frágil.
• Estrutura amigável para evolução de contratos de componente.

6) modal-bot

Use para coleta de dados em formato de formulário.

Você aprende:

• Abertura de modais e handlers de submit.
• Validação e feedback de erro em campos enviados.
• Integração de dados de modal no fluxo de comandos.

7) i18n-bot

Use quando localização é requisito principal.

Você aprende:

• Detecção de locale e carregamento de traduções.
• Composição de mensagens com utilitários sensíveis a idioma.
• Estruturação de respostas multilíngues em comandos.

8) i18n-components-bot

Use para combinar localização com fluxos complexos de componentes.

Você aprende:

• Labels e conteúdo localizados em árvores de componente.
• Estados dinâmicos de UI com consistência por idioma.
• Limites práticos de tradução em UX orientada a interação.

9) http-bot

Use quando seu bot também expõe endpoints HTTP.

Você aprende:

• Execução conjunta de runtime de bot e runtime HTTP.
• Organização de endpoints ao redor de serviços/módulos.
• Padrões básicos de middleware usados no framework.

10) webhook-bot

Use quando eventos externos devem acionar ações no Discord.

Você aprende:

• Recebimento e validação de requisições webhook.
• Despacho de eventos para handlers corretos.
• Estratégias de confiabilidade e erro explícito.

11) signal-bot

Use para padrões de comunicação orientados a eventos.

Você aprende:

• Publicação e consumo de sinais/eventos.
• Desacoplamento entre produtores e consumidores.
• Arquitetura de comunicação interna escalável.

12) schedule-bot

Use para automações recorrentes.

Você aprende:

• Tarefas agendadas e fluxo de execução estilo cron.
• Limites seguros para operações Discord em jobs.
• Organização de rotinas com observabilidade.

13) sandbox

Use como laboratório de integração.

Você aprende:

• Combinação de vários padrões do framework.
• Demonstrações de exceção e tratamento de edge cases.
• Prototipação rápida antes de extrair módulos de produção.

Trilhas recomendadas de aprendizado

Escolha uma trilha e siga a sequência para absorção mais rápida.

Trilha A: fundamentos de comandos

1. slash-bot
2. context-menu-bot
3. guard-bot

Trilha B: UX com interação intensa

1. components-bot
2. dynamic-bot
3. modal-bot
4. i18n-components-bot

Trilha C: arquitetura de backend/integração

1. http-bot
2. webhook-bot
3. signal-bot
4. schedule-bot
5. sandbox

Trilha D: produto com foco em localização

1. i18n-bot
2. i18n-components-bot
3. sandbox

Como executar um exemplo

No diretório raiz do workspace:

pnpm install
pnpm --filter @spraxium/slash-bot build
pnpm --filter @spraxium/slash-bot start

Troque @spraxium/slash-bot pelo pacote do app que você quer executar.

Fluxo prático para estudar exemplos

Use este ciclo ao analisar qualquer app:

1. Leia spraxium.config.ts para entender wiring de módulos e hooks de runtime.
2. Leia handlers em src/ primeiro, depois services/providers.
3. Execute um comando/interação completo e observe logs.
4. Modifique um único comportamento e rode novamente.
5. Mantenha experimentos úteis e descarte experimentos ruidosos rápido.

Esse método mantém seu estudo focado em fluxo de execução, e não só em leitura estática.

Notas de migração modelo atual para quem usa exemplos

Se você usou revisões anteriores dos exemplos, considere:

1. Exemplos de Component V2 agora enfatizam builders assíncronos.
2. Fluxos dinâmicos de componentes foram modernizados para payloads atuais.
3. Exemplos de HTTP/webhook seguem as interfaces mais recentes dos pacotes.
4. Manifestos dos apps foram normalizados para consistência no workspace.

Criando seu app a partir de um exemplo

Abordagem segura para produção:

1. Escolha o exemplo mais próximo do comportamento desejado, não do tamanho.
2. Copie somente módulos que você consegue explicar linha por linha.
3. Substitua variáveis de ambiente e segredos primeiro.
4. Adicione guards, logs e tratamento de erro antes de novas features.
5. Escreva testes para o primeiro fluxo crítico de comando/interação.

Os exemplos servem como referência de arquitetura, não como template pronto para produção.