convexrules

description: Guidelines and best practices for building Convex projects, including database schema design, queries, mutations, and real-world examples globs: **/*.{ts,tsx,js,jsx}

Convex guidelines

Function guidelines

New function syntax

• ALWAYS use the new function syntax for Convex functions. For example: typescript import { query } from "./_generated/server"; import { v } from "convex/values"; export const f = query({ args: {}, returns: v.null(), handler: async (ctx, args) => { // Function body }, });

Http endpoint syntax

• HTTP endpoints are defined in convex/http.ts and require an httpAction decorator. For example: typescript import { httpRouter } from "convex/server"; import { httpAction } from "./_generated/server"; const http = httpRouter(); http.route({ path: "/echo", method: "POST", handler: httpAction(async (ctx, req) => { const body = await req.bytes(); return new Response(body, { status: 200 }); }), });
• HTTP endpoints are always registered at the exact path you specify in the path field. For example, if you specify /api/someRoute, the endpoint will be registered at /api/someRoute.

Function registration

• Use internalQuery, internalMutation, and internalAction to register internal functions. These functions are private and aren't part of an app's API. They can only be called by other Convex functions.
• Use query, mutation, and action to register public functions. These functions are part of the public API and are exposed to the public Internet. Do NOT use query, mutation, or action to register sensitive internal functions that should be kept private.
• You CANNOT register a function through the api or internal objects.
• ALWAYS include argument and return validators for all Convex functions. If a function doesn't return anything, include returns: v.null() as its output validator.
• If the JavaScript implementation of a Convex function doesn't have a return value, it implicitly returns null.