convex-helpers

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.

Index

In the convex-helpers npm package:
Custom Functions
Relationship helpers
Stateful Migrations
Action retry wrapper
Rate limiting
Sessions: client-generatead
Richer useQuery
Row-level security
Zod validation
Hono for HTTP endpoints
CRUD
Validator utilities
Filter db queries with JS
Manual pagination
Query caching with ConvexQueryCacheProvider
TypeScript API Generator
OpenAPI Spec Generator
Triggers

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/ directory there's the convex-helpers directory. To use it in your own project:

 npm install convex-helpers@latest

See the README for more details.

The sections that follow are examples from which you can copy code.

Running the examples:

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.

Server-Persisted Session Data

There are two approaches to sessions data:

1. 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.

2. Create a new session document in a sessions table 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.ts for whatever your session data looks like. Here we just use {}.

Testing with a local backend

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-backend will attempt to download the binary automatically.
• Create a clearAll function to reset data between tests (see convex/testingFunctions.ts for an example)
• Start writing tests using ConvexTestingHelper.ts
• Make sure to call clearAll between tests and configure your testing framework to run one test at a time to ensure test isolation
• npm run testFunctions can be used to run these tests. This command does the following:
  • Sets up a fresh a local backend (see backendHarness.js)
  • Sets the IS_TEST environment variable to enable calling test only functions
  • Deploys code to the backend
  • Runs the tests
  • Tears down the backend

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.

🧑‍🏫 What is Convex?

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.