Loading...
; return (Loading...
} {status === "CanLoadMore" && ( )}Loading...
} `, }) export class TaskListComponent { convex = inject(ConvexService); } ``` > **Note:** The community library `@robmanganelly/ngx-convex` provides a more Angular-native experience with React-like hooks adapted for Angular DI and Signals. ## Scheduling & Cron Jobs ### One-off Scheduled Functions ```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("clear old logs", { hours: 24 }, api.logs.clearOld); crons.cron( "weekly digest", "0 9 * * 1", // Every Monday at 9 AM api.emails.sendWeeklyDigest, ); export default crons; ``` ## File Storage ```typescript // Generate an upload URL (mutation) export const generateUploadUrl = mutation({ args: {}, handler: async (ctx) => { return await ctx.storage.generateUploadUrl(); }, }); // Save file reference after 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, }); }, }); // Get a URL to serve a file (query) export const getFileUrl = query({ args: { storageId: v.id("_storage") }, handler: async (ctx, args) => { return await ctx.storage.getUrl(args.storageId); }, }); ``` ## Environment Variables ```bash # Set environment variables for your deployment npx convex env set OPENAI_API_KEY sk-... npx convex env set SENDGRID_API_KEY SG... # List current env vars npx convex env list # Remove an env var npx convex env unset OPENAI_API_KEY ``` Access in actions (NOT in queries or mutations): ```typescript // Only available in actions const apiKey = process.env.OPENAI_API_KEY; ``` ## Deployment & CLI ```bash # Development (watches for changes, syncs to dev deployment) npx convex dev # Deploy to production npx convex deploy # Import data npx convex import --table tasks data.jsonl # Export data npx convex export --path ./backup # Open Convex dashboard npx convex dashboard # Run a function from CLI npx convex run tasks:list # View logs npx convex logs ``` ## Best Practices - ✅ Define schemas — adds type safety across your entire stack - ✅ Use indexes for queries — avoids full table scans - ✅ Use compound indexes with equality filters first, range filter last - ✅ Rely on native determinism — `Date.now()` and `Math.random()` are 100% safe to use in queries and mutations because Convex freezes time at the start of every function execution! - ✅ Use `v.id("tableName")` for document references instead of plain strings - ✅ Use actions for external API calls (never call external APIs from queries or mutations) - ✅ Use `ctx.runQuery` / `ctx.runMutation` from actions — never access `ctx.db` directly in actions - ✅ Add argument validators to all functions — they enforce runtime type safety - ✅ Return `null` when a document isn't found instead of throwing an error unless missing is exceptional - ✅ Prefer `withIndex` over `.filter()` for query performance ## Anti-Patterns to Avoid 1. **❌ External API calls in queries/mutations**: Only actions can call external services. Queries and mutations run in the Convex transaction engine. 2. **❌ Doing slow CPU-bound work in mutations**: Mutations block database commits; offload heavy processing to actions. 3. **❌ Using `.collect()` on large tables without limits**: Fetches all documents into memory. Use `.take(N)` or `.paginate()`. 4. **❌ Skipping schema definition**: Without a schema you lose end-to-end type safety, the main Convex advantage. 5. **❌ Using `.filter()` instead of indexes**: `.filter()` does a full table scan. Define an index and use `.withIndex()`. 6. **❌ Storing large blobs in documents**: Use Convex file storage (`_storage`) for files; keep documents lean. 7. **❌ Circular `runQuery`/`runMutation` chains**: Actions calling mutations that schedule actions can create infinite loops. ## Common Pitfalls - **Problem:** "Query returns `undefined` on first render" **Solution:** This is expected — Convex queries are async. Check for `undefined` before rendering (this means loading, not empty). - **Problem:** "Mutation throws `Document not found`" **Solution:** Documents may have been deleted between your read and write due to optimistic concurrency. Re-read inside the mutation. - **Problem:** "`process.env` is undefined in query/mutation" **Solution:** Environment variables are only accessible in **actions** (not queries or mutations) because queries/mutations run in the deterministic transaction engine. - **Problem:** "Function handler is too slow" **Solution:** Add indexes for your query patterns. Use `withIndex()` instead of `.filter()`. For complex operations, break into smaller mutations. - **Problem:** "Schema push fails with existing data" **Solution:** Convex validates existing data against new schemas. Either migrate existing documents first, or use `v.optional()` for new fields. ## Limitations - Queries and mutations cannot call external HTTP APIs (use actions instead) - No raw SQL — you work with the Convex query builder API - Environment variables only available in actions, not in queries or mutations - Document size limit of 1MB - Maximum function execution time limits apply - No server-side rendering of Convex data without specific SSR patterns (use preloading) - Schemas are enforced at write-time; changing schemas requires data migration for existing documents ## Related Skills - `@firebase` — Alternative BaaS with Firestore (compare: Convex is TypeScript-first with ACID transactions) - `@supabase-automation` — Alternative with PostgreSQL backend (compare: Convex is document-relational with built-in reactivity) - `@prisma-expert` — ORM for traditional databases (Convex replaces both ORM and database) - `@react-patterns` — Frontend patterns that pair well with Convex React hooks - `@nextjs-app-router` — Next.js App Router integration patterns - `@authentication-oauth` — Auth patterns (Convex supports Clerk, Auth0, Convex Auth) - `@stripe` — Payment integration via Convex actions and HTTP webhooks ## Resources - [Official Docs](https://docs.convex.dev) - [Convex Stack (Blog)](https://stack.convex.dev) - [GitHub](https://github.com/get-convex/convex-backend) - [Discord Community](https://convex.dev/community) - [Convex Chef (AI Starter)](https://chef.convex.dev)