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)