convex2

---

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 create type-safe code
• 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.

Validators

• Below is an example of an array validator:

  import { mutation } from "./\_generated/server";
  import { v } from "convex/values";
  
                            export default mutation({
                            args: {
                                simpleArray: v.array(v.union(v.string(), v.number())),
                            },
                            handler: async (ctx, args) => {
                                //...
                            },
                            });
                            ```
  
  

• Below is an example of a schema with validators that codify a discriminated union type:

  import { defineSchema, defineTable } from "convex/server";
  import { v } from "convex/values";
  
                            export default defineSchema({
                                results: defineTable(
                                    v.union(
                                        v.object({
                                            kind: v.literal("error"),
                                            errorMessage: v.string(),
                                        }),
                                        v.object({
                                            kind: v.literal("success"),
                                            value: v.number(),
                                        }),
                                    ),
                                )
                            });
                            ```