convex-helpers

A collection of useful code to complement the official packages.

`convex-helpers` npm package

In the packages directory there's the convex-helpers directory, so you can npm install convex-helpers@latest.

It doesn't have all of the below features, but the ones it has can be used directly, rather than copying the code from this repo.

See the README for more details.

Server-Persisted Session Data

See the guide on Stack for tips on how to set up and use Sessions.

To use sessions, check out the files:

sessions.ts on the server-side to give you function wrappers like mutationWithSession(...).
useServerSession.ts on the client-side to give you hooks like useSessionMutation(...).
You'll need to define a table in your convex/schema.ts for whatever your session data looks like. Here we just use {}.

Authentication: withUser

See the Stack post on withUser

Use the withUser wrappers in your functions to easily look up a user. You'll need to add an entry in your schema similar to convex/schema.ts.

Row-level security

See the Stack post on row-level security

Use the RowLevelSecurity helper to define withQueryRLS and withMutationRLS wrappers to add row-level checks for a server-side function. Any access to db inside functions wrapped with these will check your access rules on read/insert/modify per-document.

Migrations: Data mutations

See the Stack post on migrations and the migration primer Stack post.

Use the migration wrapper to define a function to run over a given table. It generates an internalMutation to migrate a batch of documents.

Run the mutation to test it out, then run it over the whole table with the runMigration action.

Relationship helpers

See the Stack post on relationship helpers and the relationship schema structures post.

To use convex-helpers, import from "convex-helpers/server/relationships"

To copy code:

Use the helpers in relationships.ts to traverse database relationships in queries more cleanly.

HTTP Endpoints: Using Hono for advanced functionality

See the guide on Stack for tips on using Hono for HTTP endpoints.

To use Hono, you'll need the file honoWithConvex.ts.

Throttling client-side requests by Single-Flighting

See the Stack post on single-flighting for info on a technique to limit client requests.

You'll need the useSingleFlight.ts file, or useLatestValue.ts utilities.

Stable query results via useStableQuery

If you're fine getting stale results from queries when parameters change, check out the Stack post on useStableQuery.

You'll need the useStableQuery.ts file.

Presence

See the Stack post on implementing presence for details on how to implement presence in your app.

Related files:

presence.ts for server-side presence functions. Intended to be modified for your application.
usePresence.ts for client-side React hooks. Modify to match your server API.
(optional)useTypingIndicator.ts for specifically doing typing indicator presence.
(optional)Facepile.tsx for showing a facepile based on presence data. Intended to be used as an example to extend.

Zod Validation

Update: now Convex has argument validation. If you are just checking types, it should suffice: https://docs.convex.dev/functions/args-validation See the Stack post on Zod validation to see how to validate your Convex functions using the zod library.

You'll need the withZod.ts file.

abelcha/convex-helpers