“type instantiation is excessively deep” when importing api – growing backend makes compiler blow up
Hi Convex team & community,
We’re hitting a persistent TS2589 error and would like a sanity-check + maybe turn this into a feature request.
1. Context
Stack: Next 15.3, React 19, TypeScript 5.8.2, Convex 1.24.8
Backend: ~65 Convex functions (and growing)
Typical page code
import { api } from "@/convex/_generated/api";
const people = useQuery(api.entities.getPeopleWithFilters, args);
2. Problem
As soon as a page imports api the compiler tries to resolve the full union type of every function.
With our current backend size that exceeds the recursion limit and TS throws:
error TS2589: Type instantiation is excessively deep and possibly infinite
It happens before any cast we add to the function or return value can help.
Work-around we landed on:
// eslint-disable-next-line @typescript-eslint/no-var-requires
const api: any = require("@/convex/_generated/api").api;
This is local to the one page that fails; other files keep full typing.
4 Questions
1. Is the “expand entire api union on property access” behaviour expected?
2. Is there a lighter-weight import pattern we missed (e.g., per-function exports)?
3. Would the team consider generating a “light client” type or splitting the api type so large projects don’t blow TS’s recursion budget?
4. Happy to provide a minimal repro if needed.
Thanks for the awesome product and for any guidance!
Yuriy
We’re hitting a persistent TS2589 error and would like a sanity-check + maybe turn this into a feature request.
1. Context
Stack: Next 15.3, React 19, TypeScript 5.8.2, Convex 1.24.8
Backend: ~65 Convex functions (and growing)
Typical page code
import { api } from "@/convex/_generated/api";
const people = useQuery(api.entities.getPeopleWithFilters, args);
2. Problem
As soon as a page imports api the compiler tries to resolve the full union type of every function.
With our current backend size that exceeds the recursion limit and TS throws:
error TS2589: Type instantiation is excessively deep and possibly infinite
It happens before any cast we add to the function or return value can help.
Work-around we landed on:
// eslint-disable-next-line @typescript-eslint/no-var-requires
const api: any = require("@/convex/_generated/api").api;
This is local to the one page that fails; other files keep full typing.
4 Questions
1. Is the “expand entire api union on property access” behaviour expected?
2. Is there a lighter-weight import pattern we missed (e.g., per-function exports)?
3. Would the team consider generating a “light client” type or splitting the api type so large projects don’t blow TS’s recursion budget?
4. Happy to provide a minimal repro if needed.
Thanks for the awesome product and for any guidance!
Yuriy
