convex-tanstack_skill

Overview

This skill is a practical guide for building full-stack apps with Convex as the backend and TanStack Start as the React meta-framework. It focuses on schema design, reactive queries, mutations/actions, SSR, authentication with Better Auth, file storage, scheduling, and AI agents. Use it to implement features, debug issues, and apply best practices for a type-safe, real-time stack.

How this skill works

The skill explains how to wire Convex server functions and indexes to TanStack Start routes and loaders, showing the correct imports and patterns for cached queries, suspense queries, and mutations. It describes schema validators, index usage, authentication checks, and when to use actions versus queries/mutations. It also covers deployment considerations, file storage workflows, scheduling, and connecting Convex agents for AI features.

When to use it

• Implementing Convex queries, mutations, or actions
• Setting up or troubleshooting Better Auth authentication
• Configuring TanStack Router routes, loaders, and SSR
• Designing schema and indexes for efficient queries
• Implementing file uploads, scheduling jobs, or AI agents
• Debugging hydration, SSR, or realtime update issues

Best practices

• Always use the cached helpers import for hooks (avoid direct convex/react imports)
• Never call hooks conditionally—use the "skip" pattern for optional params
• Write validators and include returns in server functions to keep end-to-end typesafe
• Create indexes that match query field order and avoid table scans (.filter)
• Keep backend functions fast (<100ms) and avoid working over hundreds of records
• Favor queries/mutations for DB work; use actions for external API calls only

Example use cases

• Build a protected route with SSR that prefetches user data via a TanStack loader and Convex query
• Create a paginated list using an index and withIndex to ensure efficient reads
• Implement Better Auth sign-in flow and backend auth checks before mutations
• Schedule a recurring report via scheduler.runAfter or cron job that writes to Convex storage
• Wire an AI agent using @convex-dev/agent and a RAG pipeline stored in Convex documents