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.
| In this directory for copy-pasting: |
|---|
| Sessions: via a server table |
| Testing with a local backend |
| Presence |
| Throttling via single-flighting |
| Stable query results via useStableQuery |
👉 convex-helpers npm package 👈
In the packages/ there's the convex-helpers directory. To use it in your own project:
npm install convex-helpers@latestSee the README for more details.
The sections that follow are examples from which you can copy code.
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 dev script for details.
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
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:
- Either download a pre-built binary(recommended),
or build it from source.
just run-local-backendwill attempt to download the binary automatically. - 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
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.
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.