Carregando...
; return (Carregando...
} {status === "CanLoadMore" && ( )}Carregando...
} `, }) export class TaskListComponent { convex = inject(ConvexService); } ``` > **Nota:** A biblioteca community `@robmanganelly/ngx-convex` fornece uma experiência mais Angular-nativa com hooks tipo-React adaptados para Angular DI e Signals. ## Agendamento e Cron Jobs ### Funções Agendadas Únicas ```typescript import { mutation } from "./_generated/server"; import { api } from "./_generated/api"; export const sendReminder = mutation({ args: { userId: v.id("users"), message: v.string(), delayMs: v.number() }, handler: async (ctx, args) => { await ctx.scheduler.runAfter(args.delayMs, api.notifications.send, { userId: args.userId, message: args.message, }); }, }); ``` ### Cron Jobs ```typescript // convex/crons.ts import { cronJobs } from "convex/server"; import { api } from "./_generated/api"; const crons = cronJobs(); crons.interval("limpar logs antigos", { hours: 24 }, api.logs.clearOld); crons.cron( "digestão semanal", "0 9 * * 1", // Toda segunda às 9 AM api.emails.sendWeeklyDigest, ); export default crons; ``` ## Armazenamento de Arquivos ```typescript // Gerar URL de upload (mutation) export const generateUploadUrl = mutation({ args: {}, handler: async (ctx) => { return await ctx.storage.generateUploadUrl(); }, }); // Salvar referência de arquivo após upload (mutation) export const saveFile = mutation({ args: { storageId: v.id("_storage"), name: v.string() }, handler: async (ctx, args) => { await ctx.db.insert("files", { storageId: args.storageId, name: args.name, }); }, }); // Obter URL para servir um arquivo (query) export const getFileUrl = query({ args: { storageId: v.id("_storage") }, handler: async (ctx, args) => { return await ctx.storage.getUrl(args.storageId); }, }); ``` ## Variáveis de Ambiente ```bash # Definir variáveis de ambiente para seu deployment npx convex env set OPENAI_API_KEY sk-... npx convex env set SENDGRID_API_KEY SG... # Listar variáveis de env atuais npx convex env list # Remover uma variável de env npx convex env unset OPENAI_API_KEY ``` Acessar em actions (NÃO em queries ou mutations): ```typescript // Apenas disponível em actions const apiKey = process.env.OPENAI_API_KEY; ``` ## Deploy e CLI ```bash # Desenvolvimento (observa mudanças, sincroniza com deployment de dev) npx convex dev # Deploy para produção npx convex deploy # Importar dados npx convex import --table tasks data.jsonl # Exportar dados npx convex export --path ./backup # Abrir dashboard Convex npx convex dashboard # Executar uma função via CLI npx convex run tasks:list # Ver logs npx convex logs ``` ## Melhores Práticas - ✅ Defina schemas — adiciona segurança de tipo em toda a sua pilha - ✅ Use indexes para queries — evita full table scans - ✅ Use indexes compostos com filtros de igualdade primeiro, filter de range por último - ✅ Confie no determinismo nativo — `Date.now()` e `Math.random()` são 100% seguros em queries e mutations porque Convex congela o tempo no início de toda execução de função! - ✅ Use `v.id("tableName")` para referências de documentos em vez de strings simples - ✅ Use actions para chamadas de API externa (nunca chame APIs externas de queries ou mutations) - ✅ Use `ctx.runQuery` / `ctx.runMutation` de actions — nunca acesse `ctx.db` diretamente em actions - ✅ Adicione validadores de argumentos a todas as funções — eles aplicam segurança de tipo em runtime - ✅ Retorne `null` quando um documento não for encontrado em vez de lançar erro, a menos que ausência seja excepcional - ✅ Prefira `withIndex` ao `.filter()` para performance de query ## Anti-Patterns para Evitar 1. **❌ Chamadas de API externa em queries/mutations**: Apenas actions podem chamar serviços externos. Queries e mutations rodam no motor de transação Convex. 2. **❌ Fazer trabalho CPU-bound pesado em mutations**: Mutations bloqueiam commits do banco; transfira processamento pesado para actions. 3. **❌ Usar `.collect()` em tabelas grandes sem limites**: Carrega todos os documentos na memória. Use `.take(N)` ou `.paginate()`. 4. **❌ Pular definição de schema**: Sem schema você perde segurança de tipo ponta a ponta, a principal vantagem Convex. 5. **❌ Usar `.filter()` em vez de indexes**: `.filter()` faz full table scan. Defina um index e use `.withIndex()`. 6. **❌ Armazenar blobs grandes em documentos**: Use armazenamento de arquivos Convex (`_storage`) para arquivos; mantenha documentos enxutos. 7. **❌ Cadeias circulares `runQuery`/`runMutation`**: Actions chamando mutations que agendando actions podem criar loops infinitos. ## Armadilhas Comuns - **Problema:** "Query retorna `undefined` na primeira renderização" **Solução:** Isso é esperado — queries Convex são async. Verifique `undefined` antes de renderizar (significa carregando, não vazio). - **Problema:** "Mutation lança `Document not found`" **Solução:** Documentos podem ter sido deletados entre sua leitura e escrita devido a controle de concorrência otimista. Releia dentro da mutation. - **Problema:** "`process.env` é undefined em query/mutation" **Solução:** Variáveis de ambiente estão acessíveis apenas em **actions** (não queries ou mutations) porque queries/mutations rodam no motor de transação determinístico. - **Problema:** "Handler de função é muito lento" **Solução:** Adicione indexes para seus padrões de query. Use `withIndex()` em vez de `.filter()`. Para operações complexas, quebre em mutations menores. - **Problema:** "Schema push falha com dados existentes" **Solução:** Convex valida dados existentes contra novos schemas. Ou migre documentos existentes primeiro, ou use `v.optional()` para novos campos. ## Limitações - Queries e mutations não conseguem chamar APIs HTTP externas (use actions em vez disso) - Sem SQL bruto — você trabalha com a API do query builder Convex - Variáveis de ambiente disponíveis apenas em actions, não em queries ou mutations - Limite de tamanho de documento de 1MB - Limites de tempo de execução de função se aplicam - Sem server-side rendering de dados Convex sem padrões SSR específicos (use preloading) - Schemas são aplicados em write-time; mudar schemas requer migração de dados para documentos existentes ## Skills Relacionadas - `@firebase` — BaaS alternativo com Firestore (comparar: Convex é TypeScript-first com transações ACID) - `@supabase-automation` — Alternativa com backend PostgreSQL (comparar: Convex é relacional de documentos com reatividade nativa) - `@prisma-expert` — ORM para bancos tradicionais (Convex substitui ORM e banco) - `@react-patterns` — Padrões frontend que funcionam bem com hooks Convex React - `@nextjs-app-router` — Padrões de integração Next.js App Router - `@authentication-oauth` — Padrões de auth (Convex suporta Clerk, Auth0, Convex Auth) - `@stripe` — Integração de pagamento via actions Convex e webhooks HTTP ## Recursos - [Documentação Oficial](https://docs.convex.dev) - [Convex Stack (Blog)](https://