Convex TypeScript Plugin

A TypeScript plugin for working with Convex, enabling extra features in IDEs like VS Code and Cursor.

Features

Go to definition

Click on a table name to jump to its definition in your Convex schema:

export const listTasks = query({
  handler: async (ctx) => {
    const tasks = await ctx.db.query("tasks").collect();
    // cmd+click or ctrl+click here     ^     to go the schema
  },
});

Hover

Hover over a table name to see the table's definition.

Find all references

Click on the table name in your schema definition to see all places it is used (its references).

export default defineSchema({
  messages: defineTable({
    body: v.string(),
    // ^ here cmd+click or ctrl+click to see all references
  }),
});

Install

npm install @xixixao/convex-typescript-plugin

Add this plugins configuration to your tsconfig.json's compilerOptions:

{
  "compilerOptions": {
    "plugins": [{ "name": "@xixixao/convex-typescript-plugin" }]
  }
}

The tsconfig.json can be inside the convex folder or above it. Leave the other compilerOptions as they were.

Limitations

Table names use-sites

Since table names are just strings, and can be passed around, the plugin is optimistic: If you click on a string and it matches the name of one of your tables, it will be assumed to be a table name, even if it's just a coincidence.

This is also true for finding the references, so this can show places where you're not using the string as a name of a table.

Ways of defining the schema

All typical ways of defining the schema are supported. As long as TypeScript can infer the table names, you're good.

Ents schemas are also supported.

Troubleshooting

Remember that all intellisense features work off of unsaved file state, while your running Convex backend will use the deployed (previously saved) schema.

Details

Ideally we wouldn't need this plugin. The functionality could be supported directly, and better, by the TypeScript language server itself. But this is unlikely to happen any time soon, see: https://github.com/microsoft/TypeScript/issues/49033.