TypeScript

Convex provides end-to-end type support when Convex functions are written in TypeScript.

You can gradually add TypeScript to a Convex project: the following steps provide progressively better type support. For the best support you'll want to complete them all.

Example: TypeScript and Schema

Writing Convex functions in TypeScript

The first step to improving type support in a Convex project is to writing your Convex functions in TypeScript by using the .ts extension.

If you are using argument validation, Convex will infer the types of your functions arguments automatically:

convex/sendMessage.ts

import { mutation } from "./_generated/server";
import { v } from "convex/values";

export default mutation({
  args: {
    body: v.string(),
    author: v.string(),
  },

  // Convex knows that the argument type is `{body: string, author: string}`.
  handler: async ({ db }, { body, author }) => {
    const message = { body, author };
    await db.insert("messages", message);
  },
});

Otherwise you can annotate the arguments type manually:

import { mutation } from "./_generated/server";

export default mutation(
  // The only change required to convert this function to
  // TypeScript is annotating the type of the arguments object.
  async ({ db }, { body, author }: { body: string; author: string }) => {
    const message = { body, author };
    await db.insert("messages", message);
  }
);

If TypeScript is installed in your project npx convex dev and npx convex deploy will typecheck Convex functions before sending code to the Convex backend.

Convex functions are typechecked with the tsconfig.json in the Convex folder: you can modify some parts of this file to change typechecking settings, or delete this file to disable this typecheck.

You'll find most database methods have a return type of Promise<any> until you add a schema.

Adding a schema

Once you define a schema the type signature of database methods will be known. You'll also be able to use types imported from convex/_generated/dataModel in both Convex functions and application code.

The types of documents in tables can be described using Doc from the generated data model and references to documents can be described with parametrized Document IDs.

import { Doc, Id } from "../convex/_generated/dataModel";

function Channel(props: { channelId: Id<"channels"> }) { ... }
function MessagesView(props: { message: Doc<"messages"> }) { ... }

Writing frontend code in TypeScript

Invocations of useQuery and useMutation the signatures of their corresponding Convex functions. For end to end type safety, install and configure TypeScript so you can write your React components in .tsx files instead of .jsx files.

Recommended TypeScript version

Convex works best with TypeScript version 4.8.4 or newer.