Better Convex Query

TanStack Query-inspired React hooks for Convex with enhanced developer experience. Leverages Convex's built-in real-time sync engine - no additional caching needed!

🎯 Why Better Convex Query?

Convex already handles all the complex stuff (caching, retry logic, real-time subscriptions), but the basic useQuery hook lacks the developer experience of TanStack Query. This library provides:

- ✅ Full TanStack Query-style status system - status: 'loading' | 'error' | 'success'
- ✅ Enhanced loading states - isLoading vs isFetching distinction
- ✅ Smooth query transitions - keepPreviousData for flicker-free pagination
- ✅ Query caching support - Optional cache provider for extended subscription lifetimes
- ✅ Mutation callbacks - onSuccess, onError, onSettled
- ✅ Advanced TypeScript inference - Perfect type safety
- ✅ Zero additional complexity - Convex handles the hard stuff!

🚀 Installation

``bash
npm install better-convex-query


or

`tsx
import { useQuery } from 'better-convex-query';
import { api } from '../convex/_generated/api';

function UserProfile({ userId }: { userId: string }) {
const {
data,
error,
status,
isLoading,
isFetching,
isPending,
isSuccess,
isError
} = useQuery(
api.users.getUser,
{ userId },
{ enabled: !!userId }
);

if (isLoading) return

`tsx
import { useQuery } from 'better-convex-query';
import { api } from '../convex/_generated/api';

function ProjectsList() {
const [page, setPage] = useState(0);

const { data, isPlaceholderData, isFetching } = useQuery(
api.projects.list,
{ page },
{ keepPreviousData: true }
);

return (


`tsx
import { useMutation } from 'better-convex-query';
import { api } from '../convex/_generated/api';

function UpdateUserForm({ userId }: { userId: string }) {
const updateUser = useMutation(
api.users.updateUser,
{
onSuccess: (data, variables) => {
console.log('✅ User updated!', data);
},
onError: (error, variables) => {
console.error('❌ Update failed:', error);
},
onSettled: (data, error, variables) => {
console.log('📝 Update completed');
}
}
);

const handleSubmit = async (name: string) => {
try {
await updateUser.mutate({ userId, name });
} catch (error) {
// Error already handled in onError callback
}
};

return (


`tsx
import { useCacheQuery, ConvexQueryCacheProvider } from 'better-convex-query';
import { api } from '../convex/_generated/api';

// Wrap your app
function App() {
return (





);
}

// Use cached queries
function UserProfile({ userId }: { userId: string }) {
const { data } = useCacheQuery(
api.users.getUser,
{ userId }
);

return

`typescript
function useQuery>(
query: TQuery,
args: TArgs extends Record ? 'skip' | undefined : TArgs,
options?: UseQueryOptions
): UseQueryResult>
`

#### Options
- enabled?: boolean - Whether to fetch data (default: true)
- keepPreviousData?: boolean - Show previous data while new query loads (default: false)

#### Return
- data: TData | undefined - The query result data
- error: Error | undefined - Any error that occurred
- status: 'loading' | 'error' | 'success' - TanStack-style status
- isLoading: boolean - Initial load only
- isFetching: boolean - Any load (including background refetches)
- isPending: boolean - Loading or error state
- isSuccess: boolean - Has successful data
- isError: boolean - Has error
- isPlaceholderData: boolean - Whether showing previous data during transition

$3

`typescript
function useMutation>(
mutation: TMutation,
options?: UseMutationOptions
): UseMutationResult, Error, FunctionArgs>
`

#### Options
- onSuccess?: (data, variables) => void - Called on successful mutation
- onError?: (error, variables) => void - Called on mutation error
- onSettled?: (data, error, variables) => void - Called when mutation completes

#### Return
- mutate: (variables) => Promise - Trigger the mutation
- mutateAsync: (variables) => Promise - Same as mutate (alias)
- isPending: boolean - Whether mutation is running
- error: Error | undefined - Any error from last mutation
- status: 'idle' | 'pending' | 'error' | 'success' - Mutation status
- reset: () => void - Reset error and status

🎯 Key Features

$3

`bash


Install dependencies

The library includes comprehensive tests. Run with:
`bash
bun test
``

📦 Bundle Size

Since bundle size doesn't matter for this library, we prioritize:
- ✅ Perfect TypeScript inference
- ✅ Comprehensive error handling
- ✅ Full feature parity with TanStack Query patterns
- ✅ Zero runtime overhead (just wrappers around Convex)

🚀 Why This Approach?

Convex already provides:
- ✅ Real-time subscriptions
- ✅ Automatic caching
- ✅ Retry logic
- ✅ Optimistic updates
- ✅ Connection management

We add:
- ✅ Better developer experience (TanStack-style API)
- ✅ Enhanced loading states
- ✅ Mutation callbacks
- ✅ Perfect TypeScript support

We don't add:
- ❌ Additional caching (Convex handles this)
- ❌ Retry logic (Convex handles this)
- ❌ Complex state management (Convex handles this)
- ❌ Bundle bloat (just thin wrappers)

📄 License

MIT