Contribuir a Fluxo

Usa esta guía si quieres contribuir con código, documentación o ejemplos a Fluxo. Recorre la instalación local, los servicios que deberían estar en marcha, las partes del monorepo que vas a tocar más a menudo y las comprobaciones que hay que ejecutar antes de abrir una pull request.

Requisitos previos

Antes de empezar, asegúrate de que tu máquina tiene:

• Docker Desktop: necesario para levantar Postgres y Redis en local
• Bun 1.3.1: la versión fijada por este repositorio (instalar Bun)
• Git: para el control de versiones
• Herramientas de shell compatibles con Node: útiles para depurar en local y para los scripts

Inicio rápido

Clona el monorepo, instala las dependencias y arranca el stack local:

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

El comando bun dev de la raíz arranca Docker Compose y todas las tareas dev de los workspaces que seleccione Turbo. Ahora mismo eso incluye más cosas que la API y el panel, así que toma la salida del terminal como fuente de verdad y para los servicios que no necesites. Como mínimo hará esto:

1. Arrancar Docker Compose (contenedores de Postgres y Redis)
2. Arrancar el servidor de la API con Upstash Workflow en modo local
3. Arrancar la aplicación web de Next.js, los workers y las tareas de desarrollo de Tinybird

Los servicios locales de un vistazo

Cuando bun dev termine, deberías tener:

• Aplicación web: http://localhost:3000 para la landing, la documentación y el panel
• Servidor de la API: http://localhost:8787 para REST, tRPC, WebSocket y los flujos de autenticación
• Postgres: localhost:5432 para los datos relacionales
• Redis: localhost:6379 para las colas, la caché y el soporte en tiempo real
• Modo local de Upstash Workflow: las credenciales aparecen en la salida de consola de la API

Configuración de la base de datos

Conexión por defecto

La cadena de conexión de la base de datos local es:

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

Se configura automáticamente al ejecutar bun dev.

Ejecutar las migraciones

La primera vez que arranques los servicios, ejecuta las migraciones de la base de datos:

Copiarcd apps/api
bun db:migrate

Datos de ejemplo (opcional)

Para poblar la base de datos con datos de ejemplo para desarrollo:

Copiarcd apps/api
bun db:seed

Cambiar el esquema

Cuando necesites modificar el esquema de la base de datos:

1. Actualiza los archivos de esquema en apps/api/src/db/schema
2. Genera una migración:

   Copiarcd apps/api
   bun run generate

3. Aplica la migración:

   Copiarbun db:migrate

Abrir Database Studio

Para explorar la base de datos con Drizzle Studio:

Copiarcd apps/api
bun db:studio

Configuración opcional del almacenamiento

El almacenamiento de archivos en S3 solo hace falta si vas a probar subidas de archivos. Para la mayor parte del desarrollo, puedes saltarte esto.

Si de verdad necesitas S3:

1. Entra en el directorio de infraestructura:

   Copiarcd infra/aws/s3-public-setup

2. Sigue la guía de almacenamiento para la configuración recomendada de AWS, las variables de entorno que Fluxo espera en ejecución y una lista de verificación.
3. La configuración de Terraform creará los recursos de AWS necesarios para las subidas firmadas y la lectura pública de recursos.

Mapa del repositorio para colaboradores

Estos son los directorios que tocan la mayoría de quienes contribuyen:

Apps

• apps/api: backend con Hono y tRPC, con servidor WebSocket

  • APIs REST y tRPC
  • comunicación por WebSocket en tiempo real
  • consultas y escrituras en la base de datos
  • autenticación con Better Auth
  • trabajos en segundo plano con Upstash Workflow

• apps/web: aplicación de Next.js

  • landing de marketing
  • documentación (Fumadocs)
  • interfaz del panel

Paquetes

• packages/react: el SDK principal de React

  • hooks y primitivos headless
  • el componente <Support /> ya construido
  • integración con WebSocket en tiempo real

• packages/next: el SDK específico de Next.js

  • compatibilidad con Server Components
  • enlaces optimizados para Next.js

• packages/core: la lógica de cliente compartida

  • stores de gestión de estado
  • clientes REST y WebSocket
  • funciones de utilidad

• packages/types: las definiciones de TypeScript

  • tipos compartidos por todos los paquetes
  • esquemas de la API y validación

• packages/transactional: las plantillas de correo

  • plantillas de React Email
  • utilidades de correo transaccional

• packages/location: utilidades de ubicación

  • datos de países y zonas horarias
  • utilidades de geolocalización

Flujo de trabajo del colaborador

Comandos de la raíz

Ejecútalos desde la raíz del repositorio:

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 de la API

Ejecútalos desde 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

Comprobaciones de calidad antes de un pull request

Ejecuta comprobaciones acotadas mientras iteras y, antes de un cambio en un paquete publicado o en una versión, pasa las puertas del repositorio que importan para la publicación:

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

Si has tocado la API, ejecuta los tests desde apps/api. Si has tocado la documentación o las páginas de marketing, comprueba que las páginas afectadas siguen compilando y renderizándose bien.

Lista de comprobación del pull request

Antes de abrir o fusionar una PR:

1. Usa un título claro con Conventional Commits, como fix: tighten llms route indexing headers.
2. Explica qué ha cambiado, por qué y qué trabajo de seguimiento queda pendiente.
3. Enlaza la incidencia, la discusión o el hilo de soporte relacionado, si lo hay.
4. Añade capturas o grabaciones para los cambios de interfaz.
5. Añade un changeset cuando toques paquetes publicados como @fluxolat/react o @fluxolat/next.
6. Menciona las variables de entorno, migraciones o pasos de QA manual que necesite quien revise.

Notas sobre las pruebas

Fluxo usa el ejecutor de tests integrado de Bun. Los tests viven junto al código fuente, con *.test.ts y *.test.tsx.

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

Resolución de problemas

• bun dev falla nada más arrancar: comprueba que Docker Desktop está en marcha y que los puertos 3000, 8787, 5432, 6379, 7181 y 8083 están libres.
• Errores de base de datos tras traerte main: vuelve a ejecutar bun db:migrate desde apps/api para ponerte al día con los cambios de esquema.
• Faltan dependencias o el lockfile está desactualizado: vuelve a ejecutar bun install --workspaces desde la raíz del repositorio.
• Las páginas de documentación se ven pero los enlaces fallan: ejecuta bun run docs:links antes de abrir la PR.
• Solo necesitas los tests de un paquete: ejecuta bun test dentro del paquete que has cambiado en lugar de en todo el monorepo.

Formato de los mensajes de commit

Seguimos Conventional Commits para los mensajes de commit:

• feat:: funcionalidades nuevas
• fix:: corrección de errores
• docs:: cambios en la documentación
• chore:: tareas de mantenimiento
• refactor:: refactorización de código
• test:: cambios en los tests

Ejemplo: feat: add message reactions to timeline items

Changesets

Para cambios en paquetes publicados (@fluxolat/react, @fluxolat/next), añade un changeset:

Copiarbun run changeset

Sigue las indicaciones para describir tus cambios. Se usarán para generar el changelog y las subidas de versión.

Cómo obtener ayuda

• Documentación: fluxo.lat/docs
• Correo: hello@fluxo.lat

Licencia

Fluxo es software propietario de Limly LLC. Todos los derechos reservados. La AGPL permite el uso comercial sujeto a sus términos; no es una licencia «no comercial». Si necesitas obligaciones distintas, escribe a hello@fluxo.lat para preguntar por una licencia comercial alternativa.