Right now I have 6 convex queries (using query({})) that are being preloaded and fetched on front end. Would it be better to have page-specific queries that runs these query(), or should I turn everything to vanilla ts functions and just have one page-specific query that calls the vanilla ts functions.
#Questio
eager goblet
rich ironBOT
Hi @eager goblet. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:
Based on Convex best practices, you should generally keep your queries focused and modular, rather than combining all logic into a single page-specific query. The recommended approach is to write most of your logic as plain TypeScript helper functions (often in a model/ directory), and then have thin query({}) wrappers that call these helpers. This keeps your codebase maintainable and makes it easier to refactor or reuse logic across different queries or mutations.
If you have six distinct pieces of data that your page needs, it's usually better to keep them as separate queries, each responsible for a specific concern. This leverages Convex's reactive sync engine, which efficiently manages caching and consistency for each query. Combining everything into a single query can make your code harder to maintain and less flexible, and you lose the benefits of fine-grained reactivity and caching.
However, if you have a set of data that is always fetched together and is tightly coupled, you could create a page-specific query that orchestrates calls to your helper functions and returns a combined result. But you should still keep the heavy lifting in plain TypeScript helpers, not in the query handler itself. The key is to avoid duplicating logic and to keep your API surface clean and maintainable.
Summary:
- Keep most logic in plain TypeScript helpers.
- Use thin query wrappers to expose API endpoints.
- Only combine queries if the data is always needed together and tightly coupled.
- Avoid turning everything into a single query just for the sake of reducing the number of queries; let Convex handle caching and reactivity for you.
References:
- Use helper functions to write shared code
- Splitting up query code via helpers
- The Zen of Convex: Let Convex handle caching & consistency
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
eager goblet
@rich iron woild combining help initial page load (preloading)?
rich ironBOT
Let me check the knowledge base for you again. One moment! :books:
Combining multiple queries into a single page-specific query can help with initial page load when preloading data, especially in server-side rendering scenarios. This is because making a single network request to fetch all required data can reduce round trips and ensure consistency between related data, avoiding issues where different queries might see slightly different database states if run separately in a stateless context like SSR.
For example, in Next.js or TanStack Start, server-side rendering typically fetches data ad-hoc (not via a stateful WebSocket session), which can lead to inconsistencies if multiple queries are run independently. By combining them, you ensure all data is fetched at the same logical timestamp, providing a consistent view for the initial render Server-side Rendering with TanStack Start Next.js Server Rendering Consistency.
However, after the initial load, Convex’s client-side reactivity and caching work best with modular queries. So, while combining queries can help with SSR preloading, you should balance this with maintainability and reactivity needs for the rest of your app.
In summary:
- Combining queries can help with initial page load consistency and performance during preloading/SSR.
- For client-side reactivity and maintainability, keep queries modular unless the data is always needed together.