Contribuir com o Fluxo

Use este guia se você quer contribuir com código, documentação ou exemplos para o Fluxo. Ele percorre a instalação local, os serviços que devem estar rodando, as partes do monorepo que você vai mexer com mais frequência e as verificações a rodar antes de abrir uma pull request.

Pré-requisitos

Antes de começar, confira se a sua máquina tem:

• Docker Desktop: necessário para subir o Postgres e o Redis localmente
• Bun 1.3.1: a versão fixada por este repositório (instalar o Bun)
• Git: para o controle de versão
• Ferramentas de shell compatíveis com Node: úteis para depurar localmente e para os scripts

Início rápido

Clone o monorepo, instale as dependências e suba a stack local:

Copiargit clone https://github.com/fluxolat/fluxo.git
cd fluxo
bun install
bun dev

O comando bun dev da raiz sobe o Docker Compose e todas as tarefas dev dos workspaces selecionadas pelo Turbo. Hoje isso inclui mais coisas do que a API e o painel, então use a saída do terminal como fonte da verdade e pare os serviços de que você não precisa. No mínimo, ele vai:

1. Subir o Docker Compose (contêineres de Postgres e Redis)
2. Subir o servidor da API com o Upstash Workflow em modo local
3. Subir o app web em Next.js, os workers e as tarefas de desenvolvimento do Tinybird

Os serviços locais num relance

Quando o bun dev terminar, você deve ter:

• App web: http://localhost:3000 para a landing, a documentação e o painel
• Servidor da API: http://localhost:8787 para REST, tRPC, WebSocket e os fluxos de autenticação
• Postgres: localhost:5432 para os dados relacionais
• Redis: localhost:6379 para as filas, o cache e o suporte em tempo real
• Modo local do Upstash Workflow: as credenciais aparecem na saída de console da API

Configuração do banco de dados

Conexão padrão

A string de conexão do banco de dados local é:

postgresql://postgres:postgres@localhost:5432/fluxo

Isso é configurado automaticamente ao rodar bun dev.

Rodar as migrações

Na primeira vez que você subir os serviços, rode as migrações do banco de dados:

Copiarcd apps/api
bun db:migrate

Dados de exemplo (opcional)

Para popular o banco de dados com dados de exemplo para desenvolvimento:

Copiarcd apps/api
bun db:seed

Alterar o schema

Quando você precisar modificar o schema do banco de dados:

1. Atualize os arquivos de schema em apps/api/src/db/schema
2. Gere uma migração:

   Copiarcd apps/api
   bun run generate

3. Aplique a migração:

   Copiarbun db:migrate

Abrir o Database Studio

Para explorar o banco de dados com o Drizzle Studio:

Copiarcd apps/api
bun db:studio

Configuração opcional do armazenamento

O armazenamento de arquivos no S3 só é necessário se você for testar uploads de arquivos. Para a maior parte do desenvolvimento, você pode pular isso.

Se você realmente precisar do S3:

1. Entre no diretório de infraestrutura:

   Copiarcd infra/aws/s3-public-setup

2. Siga o guia de armazenamento para a configuração recomendada da AWS, as variáveis de ambiente que o Fluxo espera em execução e uma lista de verificação.
3. A configuração do Terraform criará os recursos da AWS necessários para os uploads assinados e a leitura pública de recursos.

Mapa do repositório para colaboradores

Estes são os diretórios que a maioria de quem contribui mexe:

Apps

• apps/api: backend com Hono e tRPC, com servidor WebSocket

  • APIs REST e tRPC
  • comunicação por WebSocket em tempo real
  • consultas e escritas no banco de dados
  • autenticação com o Better Auth
  • jobs em segundo plano com o Upstash Workflow

• apps/web: app em Next.js

  • landing de marketing
  • documentação (Fumadocs)
  • interface do painel

Pacotes

• packages/react: o SDK principal de React

  • hooks e primitivos headless
  • o componente <Support /> pronto
  • integração com WebSocket em tempo real

• packages/next: o SDK específico do Next.js

  • suporte a Server Components
  • bindings otimizados para o Next.js

• packages/core: a lógica de cliente compartilhada

  • stores de gerenciamento de estado
  • clientes REST e WebSocket
  • funções utilitárias

• packages/types: as definições de TypeScript

  • tipos compartilhados por todos os pacotes
  • schemas da API e validação

• packages/transactional: os templates de e-mail

  • templates do React Email
  • utilitários de e-mail transacional

• packages/location: utilitários de localização

  • dados de países e fusos horários
  • utilitários de geolocalização

Fluxo de trabalho do colaborador

Comandos da raiz

Rode estes a partir da raiz do repositório:

Copiar# Start all services
bun dev
 
# Build all packages
bun run build
 
# Build specific package
bun run build --filter @fluxolat/react
 
# Run linter and auto-fix issues
bun run fix
 
# Type check all packages
bun run check-types
 
# Check documentation links
bun run docs:links
 
# Run all workspace tests
bun run test
 
# Check generated OpenAPI and published-package release gates
bun run check:openapi
bun run check:browser-embed-size

Comandos específicos da API

Rode estes a partir de apps/api:

Copiar# Start API server only
bun run dev
 
# Run migrations
bun run db:migrate
 
# Seed database
bun run db:seed
 
# Open Drizzle Studio
bun run db:studio
 
# Generate Better Auth schema
bun run better-auth:generate-schema

Verificações de qualidade antes de um pull request

Rode verificações focadas enquanto itera e, antes de uma mudança em um pacote publicado ou em uma release, passe pelos portões do repositório relevantes para a publicação:

Copiar# Auto-fix linting issues across the repo
bun run fix
 
# Verify TypeScript types
bun run check-types
 
# Run docs link checks for documentation edits
bun run docs:links
 
# Run tests in the package or app you changed
cd packages/react
bun test
 
# From the repository root before release-sensitive changes
bun run test
bun run build
bun run check:openapi
bun run check:browser-embed-size

Se você mexeu na API, rode os testes a partir de apps/api. Se mexeu na documentação ou nas páginas de marketing, confira se as páginas afetadas continuam compilando e renderizando bem.

Lista de verificação do pull request

Antes de abrir ou dar merge em um PR:

1. Use um título claro com Conventional Commits, como fix: tighten llms route indexing headers.
2. Explique o que mudou, por que mudou e qual trabalho de acompanhamento ainda está pendente.
3. Vincule a issue, a discussão ou o tópico de suporte relacionado, quando houver.
4. Acrescente capturas ou gravações para as mudanças de interface.
5. Acrescente um changeset quando mexer em pacotes publicados como @fluxolat/react ou @fluxolat/next.
6. Mencione as variáveis de ambiente, migrações ou passos de QA manual de que quem revisa vai precisar.

Notas sobre os testes

O Fluxo usa o executor de testes embutido do Bun. Os testes ficam ao lado do código-fonte, com *.test.ts e *.test.tsx.

Copiar# Run tests in a specific package
cd packages/react
bun test
 
# Watch mode
bun test --watch
 
# Coverage report
bun test --coverage

Solução de problemas

• bun dev falha logo de cara: confira se o Docker Desktop está rodando e se as portas 3000, 8787, 5432, 6379, 7181 e 8083 estão livres.
• Erros de banco de dados depois de puxar a main: rode de novo bun db:migrate a partir de apps/api para se atualizar com as mudanças de schema.
• Faltam dependências ou o lockfile está desatualizado: rode de novo bun install --workspaces a partir da raiz do repositório.
• As páginas de documentação aparecem mas os links falham: rode bun run docs:links antes de abrir o PR.
• Você só precisa dos testes de um pacote: rode bun test dentro do pacote que você mudou em vez de no monorepo inteiro.

Formato das mensagens de commit

Seguimos os Conventional Commits para as mensagens de commit:

• feat:: novas funcionalidades
• fix:: correção de erros
• docs:: mudanças na documentação
• chore:: tarefas de manutenção
• refactor:: refatoração de código
• test:: mudanças nos testes

Exemplo: feat: add message reactions to timeline items

Changesets

Para mudanças em pacotes publicados (@fluxolat/react, @fluxolat/next), acrescente um changeset:

Copiarbun run changeset

Siga as instruções para descrever as suas mudanças. Elas serão usadas para gerar o changelog e os incrementos de versão.

Como obter ajuda

• Documentação: fluxo.lat/docs
• E-mail: hello@fluxo.lat

Licença

O Fluxo é software proprietário da Limly LLC. Todos os direitos reservados. A AGPL permite o uso comercial nos termos dela; não é uma licença “não comercial”. Se você precisa de obrigações diferentes, escreva para hello@fluxo.lat e pergunte por uma licença comercial alternativa.