guidelines-for-building-convex-projects

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.

Validators

• Below is an example of an array validator: ```typescript 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: ```typescript 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(),
                                    }),
                                ),
                            )
                        });
                        ```
  

• Always use the v.null() validator when returning a null value. Below is an example query that returns a null value: ```typescript import { query } from "./_generated/server"; import { v } from "convex/values";

                              export const exampleQuery = query({
                                args: {},
                                returns: v.null(),
                                handler: async (ctx, args) => {
                                    console.log("This query returns a null value");
                                    return null;
                                },
                              });
                              ```
  

• Here are the valid Convex types along with their respective validators: Convex Type | TS/JS type | Example Usage | Validator for argument validation and schemas | Notes | | ----------- | ------------| -----------------------| -----------------------------------------------| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Id | string | doc._id | v.id(tableName) | | | Null | null | null | v.null() | JavaScript's undefined is not a valid Convex value. Functions the return undefined or do not return will return null when called from a client. Use null instead. | | Int64 | bigint | 3n | v.int64() | Int64s only support BigInts between -2^63 and 2^63-1. Convex supports bigints in most modern browsers. | | Float64 | number | 3.1 | v.number() | Convex supports all IEEE-754 double-precision floating point numbers (such as NaNs). Inf and NaN are JSON serialized as strings. | | Boolean | boolean | true | v.boolean() | | String | string | "abc" | v.string() | Strings are stored as UTF-8 and must be valid Unicode sequences. Strings must be smaller than the 1MB total size limit when encoded as UTF-8. | | Bytes | ArrayBuffer | new ArrayBuffer(8) | v.bytes() | Convex supports first class bytestrings, passed in as ArrayBuffers. Bytestrings must be smaller than the 1MB total size limit for Convex types. | | Array | Array] | [1, 3.2, "abc"] | v.array(values) | Arrays can have at most 8192 values. | | Object | Object | {a: "abc"} | v.object({property: value}) | Convex only supports "plain old JavaScript objects" (objects that do not have a custom prototype). Objects can have at most 1024 entries. Field names must be nonempty and not start with "$" or "". | | Record | Record | {"a": "1", "b": "2"} | v.record(keys, values) | Records are objects at runtime, but can have dynamic keys. Keys must be only ASCII characters, nonempty, and not start with "$" or "". |