A collection of useful code to complement the official packages. This directory has a project with examples of using convex-helpers. You can find the npm package in ./packages/convex-helpers.
convex-helpers npm package
In the packages directory there's the convex-helpers directory. To use it:
npm install convex-helpers@latestIt 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.
To run these locally, run: npm i && npm run dev.
This will symlink the packages/convex-helpers directory so you can edit the
convex helpers source while using it in this example project.
It will also run chokidar to re-compile convex-helpers on file changes.
See the watch script for details.
Build your own customized versions of query, mutation, and action that
define custom behavior, allowing you to:
- Run authentication logic before the request starts.
- Look up commonly used data and add it to the ctx argument.
- Replace a ctx or argument field with a different value, such as a version
of
dbthat runs custom functions on data access. - Consume arguments from the client that are not passed to the action, such as taking in an authentication parameter like an API key or session ID. These arguments must be sent up by the client along with each request.
See more in the convex-helpers README.
To validate your arguments with zod instead of the
built-in argument validation,
you can import from convex-helpers from "convex-helpers/server/zod".
Read more in the Stack post.
There are two approaches to sessions data:
-
Creating a session ID client-side and passing it up to the server on every request. This is the recommended approach and is available by importing from
"convex-helpers/server/sessions". See more in the convex-helpers README. -
Create a new session document in a
sessionstable for every new client, where you can store associated data. See this article on Stack for tips on how to set up and use Sessions. To use theses sessions, copy the files:- server/sessions.ts on the server-side to give you action utilities like
ctx.runSessionQuery(...). - react/session.ts on the client-side to give you hooks like
useSessionMutation(...). - You'll need to define a table in your
convex/schema.tsfor whatever your session data looks like. Here we just use{}.
- server/sessions.ts on the server-side to give you action utilities like
Use helper functions to retry a Convex action until it succeeds.
See the Stack post on retrying actions and the convex-helpers package README for examples and usage.
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.
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.
See the Stack post on migrations and the migration primer Stack post.
See the convex-helpers package for examples and usage.
See the Stack post on relationship helpers and the relationship schema structures post.
To use convex-helpers, import from "convex-helpers/server/relationships"
See more in the convex-helpers README.
To copy code: Use relationships.ts to traverse database relationships in queries more cleanly.
Hono is an optimized web framework you can use to define
HTTP API endpoints easily
(httpAction in Convex).
See the guide on Stack for tips on using Hono for HTTP endpoints.
To use convex-helpers, import from "convex-helpers/server/hono"
See more in the convex-helpers README.
To generate a basic CRUD api for your tables, you can use this helper to define these functions for a given table:
createreadupdatedeletepaginate
To use convex-helpers, import { crud } from "convex-helpers/server"
See more in the convex-helpers README.
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.
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.
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.
When using validators for defining database schema or function arguments, these validators help:
- Add a
Tableutility that defines a table and keeps references to the fields to avoid re-defining validators. To learn more about sharing validators, read this article, an extension of this article. - Add utilties for partial, pick and omit to match the TypeScript type utilities.
- Add shorthand for a union of
literals, anullablefield, adeprecatedfield, andbrandedString. To learn more about branded strings see this article. - Make the validators look more like TypeScript types, even though they're runtime values. (This is controvercial and not required to use the above).
See more in the convex-helpers README.
convex/example.test.ts demonstrates testing Convex functions by running them against a local backend.
See this Stack article for more information.
To set these up for yourself:
- Clone the Convex open source backend repo and follow setup instructions
- Create a
clearAllfunction to reset data between tests (seeconvex/testingFunctions.tsfor an example) - Start writing tests using
ConvexTestingHelper.ts - Make sure to call
clearAllbetween tests and configure your testing framework to run one test at a time to ensure test isolation npm run testFunctionscan be used to run these tests. This command does the following:- Sets up a fresh a local backend (see backendHarness.js)
- Sets the
IS_TESTenvironment variable to enable calling test only functions - Deploys code to the backend
- Runs the tests
- Tears down the backend
Convex is a hosted backend platform with a
built-in database that lets you write your
database schema and
server functions in
TypeScript. Server-side database
queries automatically
cache and
subscribe to data, powering a
realtime useQuery hook in our
React client. There are also clients for
Python,
Rust,
ReactNative, and
Node, as well as a straightforward
HTTP API.
The database supports NoSQL-style documents with opt-in schema validation, relationships and custom indexes (including on fields in nested objects).
The
query and
mutation server functions have transactional,
low latency access to the database and leverage our
v8 runtime with
determinism guardrails
to provide the strongest ACID guarantees on the market:
immediate consistency,
serializable isolation, and
automatic conflict resolution via
optimistic multi-version concurrency control (OCC / MVCC).
The action server functions have
access to external APIs and enable other side-effects and non-determinism in
either our
optimized v8 runtime or a more
flexible node runtime.
Functions can run in the background via scheduling and cron jobs.
Development is cloud-first, with hot reloads for server function editing via the CLI, preview deployments, logging and exception reporting integrations, There is a dashboard UI to browse and edit data, edit environment variables, view logs, run server functions, and more.
There are built-in features for reactive pagination, file storage, reactive text search, vector search, https endpoints (for webhooks), snapshot import/export, streaming import/export, and runtime validation for function arguments and database data.
Everything scales automatically, and it’s free to start.