Components for your Backend
With Convex Components, you can incorporate off-the-shelf features into your app. They enable an ecosystem of powerful building blocks to reduce the amount of code you have to write and maintain yourself. These vary from new database features like providing geospatial search, drop-in features like LaunchDarkly feature flags or Expo push notifications, or common utilities to retry or cache actions (Convex’s serverless functions that can have side effects).
In this post we’ll cover:
- What are components and why they’re a powerful abstraction.
- What it looks like to add some components to an existing app.
- Best practices for using components.
What are Convex Components?
Components can be thought of as a combination of concepts from frontend components, third party APIs, and both monolith and service-oriented architectures.
If you’re already sold and looking to jump right in you can skip this section. If you’re interested in the larger conceptual model they fit into, check out The Software-Defined Database.
Without further ado, here are some of the component capabilities I’m excited about.
Data
Similar to frontend components, Convex Components encapsulate state and behavior, and allow exposing a clean interface. However, instead of just storing state in memory, these can have internal state machines that can persist between user sessions, span users, and change in response to external inputs, such as webhooks. Components can store data in a few ways:
- Database tables with their own schema validation definitions. Since Convex is realtime by default, data reads are automatically reactive, and writes commit transactionally.
- File storage, independent of the main app’s file storage.
- Durable functions via the built-in function scheduler. Components can reliably schedule functions to run in the future and pass along state.
Typically, libraries require configuring a third party service to add stateful off-the-shelf functionality, which lack the transactional guarantees that come from storing state in the same database.
Isolation
Similar to regular npm libraries, Convex Components include functions, type safety, and are called from your code. However, they also provide extra guarantees.
- Similar to a third-party API, components can’t read data for which you don’t provide access. This includes database tables, file storage, environment variables, scheduled functions, etc.
- Similar to service-oriented architecture, functions in components are run in an isolated environment, so they can’t read or write global variables or patch system behavior.
- Similar to a monolith architecture, data changes commit transactionally across calls to components, without having to reason about complicated distributed commit protocols or data inconsistencies. You’ll never have a component commit data but have the calling code roll back.
- In addition, each call to a component is a sub-transaction isolated from other calls1, allowing you to safely catch errors thrown by components. It also allows component authors to easily reason about state changes without races, and trust that a thrown exception will always roll back the Component’s sub-transaction.
Encapsulation
Being able to reason about your code is essential to scaling a codebase. Components allow you to reason about API boundaries and abstractions.
- The transactional guarantees discussed above allows authors and users of components to reason locally about data changes.
- Components expose an explicit API, not direct database table access. Data invariants can be enforced in code, within the abstraction boundary. For example, the aggregate component can internally denormalize data, the rate limiter component can shard its data, and the push notification component can internally batch API requests, while maintaining simple interfaces.
- Runtime validation ensures all data that cross a component boundary are validated: both arguments and return values. As with normal Convex functions, the validators also specify the TypeScript types, providing end-to-end typing with runtime guarantees.
Adding components to your app: walkthrough
To make this concrete, let’s look at what it takes to add some components to an existing app I’m working on. It’s an embeddings-based word game where you submit word guesses that match the meaning of two target words. Let’s add:
- An aggregate component for a leaderboard to track top scores, calculate ranks, etc.
- An action cache to only ever calculate an embedding once for a given word.
- A rate limiter for how fast guest users can join, and how fast you can submit guesses.
- A sharded counter to scalably track total guesses.
- A migration manager, to manage our online migrations.
The full diff can be seen in this pull request, with a commit for each step of the way. Note: the rate limiter and migration components are conversions from the convex-helpers
equivalents. With components, they no longer need to add tables to your main schema.
npm i convex@latest
npm i @convex-dev/aggregate @convex-dev/action-cache @convex-dev/sharded-counter @convex-dev/ratelimiter @convex-dev/migrations
As covered in the docs and each component’s README (as seen in the components gallery, npm, or GitHub), adding a component involves:
-
Adding a new file to your project:
convex.config.ts
where you configure which components your app uses.// convex/convex.config.ts: import { defineApp } from "convex/server"; import aggregate from "@convex-dev/aggregate/convex.config"; import actionCache from "@convex-dev/action-cache/convex.config"; import shardedCounter from "@convex-dev/sharded-counter/convex.config"; import ratelimiter from "@convex-dev/ratelimiter/convex.config"; import migrations from "@convex-dev/migrations/convex.config"; const app = defineApp(); app.use(aggregate, { name: "leaderboard" }); app.use(actionCache); app.use(shardedCounter); app.use(ratelimiter); app.use(migrations); export default app;
-
Running
npx convex dev
to generate code for associated components, so you have type-safe access to them viaimport { components } from "./_generated/api";
$ npx convex dev # ... ✔ Installed component actionCache. ✔ Installed component aggregate. ✔ Installed component migrations. ✔ Installed component ratelimiter. ✔ Installed component shardedCounter.
-
Instantiating the helper Class(es) for the components, which wrap up the underlying component API calls and provide conveniences like generic types. We’ll look at each of them next.
Adding a leaderboard with the aggregate
component
To get a leaderboard, we can define an aggregate and connect it to table updates using Triggers. Here we make an aggregate that’s sorted by gameId, then by score. The configuration ends up looking like:
// in convex/functions.ts
import {
internalMutation as internalMutationRaw,
mutation as mutationRaw,
} from "./_generated/server";
import { Triggers } from "convex-helpers/server/triggers";
import { TableAggregate } from "@convex-dev/aggregate";
import { customCtx, customMutation } from "convex-helpers/server/customFunctions";
import { DataModel, Id } from "./_generated/dataModel";
import { components } from "./_generated/api";
const triggers = new Triggers<DataModel>();
const leaderboard = new TableAggregate<
[Id<"games">, number],
DataModel,
"guesses"
>(components.leaderboard, {
sortKey: (d) => [d.gameId, d.score],
sumValue: (d) => d.score,
});
triggers.register("guesses", leaderboard.trigger());
const mutation = customMutation(mutationRaw, customCtx(triggers.wrapDB));
const internalMutation = customMutation(
internalMutationRaw,
customCtx(triggers.wrapDB),
);
Note: in order to keep the aggregate up to date, you need to use these versions of mutation
and internalMutation
instead of the built-in ones. You can see in this commit where I make this change along with adding an ESLint rule to prevent anyone from accidentally importing the “raw” versions of them.
To find the high score for a game, I can use max
:
leaderboard.max(ctx, { prefix: [args.gameId] });
To find the rank of my best guess amongst all guesses for a game, I can use offsetOf
:
leaderboard.offsetOf(ctx, [args.gameId, bestGuess.score], bestGuess._id, { prefix: [args.gameId] });
Read the docs for a full rundown of its capabilities.
Caching embeddings with action-cache
For my game, I use embeddings of every search a user enters. To avoid generating duplicates, I can use the Action Cache component:
const embedCache = new ActionCache(components.actionCache, {
action: internal.embed.generateEmbedding,
});
Instead of calling the action directly, I can call it through the cache, which will return the cached value (based on the function name and arguments), or generate one on the fly.
await embedCache.fetch(ctx, { model: CONFIG.embeddingModel, input: text });
Tip: by including the model in the arguments, I ensure that it will never return cached embeddings generated by a different model, since the args are part of the cache key.
Read the docs to learn about setting an expiration policy or manually clearing values.
Tracking fast-changing stats with sharded-counter
With the hopes that my game will become a grand success, I want to count not only the guesses within a daily game, but across all days. I’d also like a global count on the homepage including all games by all authors. As you may have seen with One Million Checkboxes, keeping a count fast and correct can be nontrivial. Sharded Counter isn’t as fully-featured as Aggregate, but it excels at high throughput counting.
Configuration:
import { ShardedCounter } from "@convex-dev/sharded-counter";
const counter = new ShardedCounter(components.shardedCounter);
Adding to counters when adding a guess, but only for active games:
//inside the function used to add guesses
if (game.active) {
await counter.add(ctx, "total"); // overall guesses vanity metric
await counter.add(ctx, args.gameId); // individual daily game
await counter.add(ctx, game.namespaceId); // daily games share a namespace
await counter.add(ctx, args.userId); // how many guesses a user has ever made
}
return ctx.db.insert("guesses", { ... });
I can then add live-updating stats to various parts of the UI showing activity, without worrying about query performance.
const totalCount = await counter.count(ctx, "total");
Note: be careful about calling count
within mutations, since any two mutations both adding and reading the count will conflict with each other, requiring one to retry. Read more about that here.
Using ratelimiter
to deter abuse
Using application-layer rate limits allows you to control how frequently things can happen. Here I added a simple limit on how fast users can sign in as a guest (to hamper floods of automated signups).
const rate = new RateLimiter(components.ratelimiter, {
anonymousSignIn: {
kind: "token bucket",
rate: 100,
period: MINUTE,
shards: 10,
},
});
It is then used as part of the sign up flow:
await rate.limit(ctx, "anonymousSignIn", { throws: true });
It will throw an exception if the rate is exceeded, rolling back the transaction.
Similar to the counter, it can be configured with the number of shards to enable more parallelism by distributing the load. More shards come with a higher chance of rejecting a request erroneously when running close to the limit, as the capacity is distributed amongst them.
See the docs for more information.
Configuring stateful migrations
Migrations allow us to modify data. The component makes it easy: you define a function that modifies a single row, and it will run it in batches and keep track of the bookkeeping.
Configuration:
export const migrations = new Migrations<DataModel>(components.migrations, {
internalMutation,
});
Note: we pass in the internalMutation
we made when configuring the aggregate
component. That way if our migrations ever modify the guesses
table, it will keep the associated aggregate information updated.
While the app doesn’t need to modify any data right now, it does need to update the aggregates and counters for guesses submitted before we added the above counter logic. So we’ll define a “migration” over the guesses table that, instead of modifying each guess, updates the counters and leaderboard. We’ll limit it to only the guesses submitted before we deployed the counter change, so we don’t double-count any guesses.
// in convex/game.ts
export const addOldGuesses = migrations.define({
table: "guesses",
customRange: (query) =>
query.withIndex("by_creation_time", (q) =>
q.lt("_creationTime", Number(new Date("2024-10-22T16:20:00.000Z"))),
),
migrateOne: async (ctx, doc) => {
await leaderboard.insertIfDoesNotExist(ctx, doc);
const game = await ctx.db.get(doc.gameId);
if (!game?.active) {
return;
}
await counter.add(ctx, "total");
await counter.add(ctx, doc.gameId);
await counter.add(ctx, game.namespaceId);
await counter.add(ctx, game.userId);
},
});
export const backfill = migrations.runFromCLI(internal.game.addOldGuesses);
We could run it from the dashboard or CLI: npx convex run game:backfill
.
If we had a bug and it failed part way, we could see how many guesses it had processed, resume where it left off, test a dry run, or start over after. By default if we run it again it will no-op:
$ npx convex run game:backfill
[CONVEX ?(game:backfill)] [DEBUG] 'Migration already done.'
{
cursor: '07b6def...',
isDone: true,
latestStart: 1729614001337,
name: 'game:addOldGuesses',
processed: 8675
}
Walkthrough done!
Check out convex.dev/components to see the full list of components available now, and let us know what you’d like to see.
Best practices for using components
Avoid modifying data directly from the dashboard
You can see your component’s data and its internal functions on the dashboard by selecting it from the components dropdown (you won’t see this dropdown until you have your first component, by the way). However, directly modifying the data or running internal functions might violate some invariant the component depends on. Limit interacting with it through the Class it provides, through functions in your own application.
Using multiple component instances
Some components make sense to only have a single instance of, for instance you probably only need one crons component for dynamically periodic function calls. For others, you’ll need to have multiple components for different use cases. It’s important to know when to make multiple component instances.
One thing that can be confusing is that when I say “multiple components” I mean multiple calls to app.use(somecomponent, { name: "uniqueName" })
. Conceptually, every call to .use
makes a new component that has its own isolated database tables. Merely instantiating the component’s Class multiple times via new SomeComponent(components.somecomponent)
will have multiple references to the same component. For some components this is fine. For instance, for rate limiting each limit has its own name, and different Class instances can point to the same component instance:
const userLimits = new RateLimiter(components.ratelimiter, {
freeTrialSignUp: { kind: "fixed window", rate: 100, period: HOUR },
//...
};
// OK
const messageLimits = new RateLimiter(components.ratelimiter, {
sendMessage: { kind: "token bucket", rate: 10, period: MINUTE, capacity: 3 },
});
As long as the names don’t conflict, they can happily use the same component. However, for the aggregates component, you need to make sure each table you’re aggregating over has its own data:
// convex/convex.config.ts
app.use(aggregate, { name: "aggregateScores" });
app.use(aggregate, { name: "aggregateByGame" });
// convex/foo.ts
const byScores = new TableAggregate(components.aggregateScores, {...});
const byGame = new TableAggregate(components.aggregateByGame, {...});
Am I locked in?
Similar to using a third party service as part of your app, using components means that some of your app’s data is stored in isolated tables. When you decide to change third-party providers, you need to think about how your data will transfer. Similarly with components, you will need to get your data out of the component.
- Rest assured that the data is still in your Convex database. You can see the data from the Convex dashboard, and it is included in snapshot imports and exports, allowing your components to restore from a backup at the same snapshot as the rest of your data.
- If you want to modify the behavior of a component, you are free to fork or vendor in the implementation. Components need not be installed by npm. You can add functions, modify the schema, etc.
- For now, component data is tied to the component’s name. Each component has a default name (for instance the action cache is named
actionCache
by default), but can be overridden when installing likeapp.use(ratelimiter, { name: "customName" })
. This means you can replace a component and maintain its data by re-using the same name, provided it has a compatible schema to the existing data.
Summary
Components are a big step forward in the composability of backend functionality, bringing the enforced isolation and local-reasoning benefits of service-oriented architecture together with the transactional simplicity of monolith architecture. It allows encapsulating logic and data to build powerful features that can ship in a tidy package with a clean abstraction layer. As always, let us know what you think in Discord.
Footnotes
-
Components function calls provide serializable isolation, the strongest level, mirroring Convex mutations. This means two calls can each read from the database, modify it, and write it back without worrying about race conditions. ↩
Convex is the sync platform with everything you need to build your full-stack project. Cloud functions, a database, file storage, scheduling, search, and realtime updates fit together seamlessly.