Typecheck Performance
For AI agents: see llms.txt for the complete documentation index. Markdown versions are available by adding .md to a page URL or requesting Accept: text/markdown.
When you are experiencing slow typechecking performance when pushing code to
your Convex deployment (e.g. when running npx convex dev), there are a few
different strategies you can try to improve performance or debug typechecking
bottlenecks.
Use the TypeScript 7 compiler
TypeScript 7's native compiler is generally much faster than earlier versions of TypeScript. To use it, install it as your project's TypeScript version. Convex will use it automatically.
npm install --save-dev typescript@^7
TypeScript 7.0 does not include a JavaScript API, so if other tools in your project need it, follow TypeScript's side-by-side installation instructions. Convex picks up TypeScript 7 in that setup too.
Debug slow typechecking
Sometimes the TypeScript compiler can get stuck in a complex type inference
loop. Often, adding a single manual type can help break the loop. You can
use the generateTrace flag
to determine where the compiler is spending the most time:
npx tsc -p path/to/convex --generateTrace output_directory --incremental false
Use static codegen
Static codegen is currently a beta feature. If you have feedback or feature requests, let us know on Discord!
Using static codegen can improve typechecking performance, but currently comes with some caveats.
Disable typechecking
You can disable typechecking using the --typecheck=disable option with
npx convex dev and npx convex deploy. In general, we do not recommend
disabling typechecking. However, this can be used as a last resort workaround.