Skip to main content

​
Installation

Get the Aggregate component set up in your Convex project in just a few steps.

​
Prerequisites

You’ll need an existing Convex project. If you don’t have one yet:
1

Create a new Convex project

Run one of these commands to set up Convex:
npm create convex
Or follow the Convex quickstart guide to get started.

​
Install the Component

1

Install the npm package

Add the @convex-dev/aggregate package to your project:
npm install @convex-dev/aggregate
2

Configure the component

Create or update convex/convex.config.ts in your project and register the aggregate component:
convex/convex.config.ts
import { defineApp } from "convex/server";
import aggregate from "@convex-dev/aggregate/convex.config";

const app = defineApp();
app.use(aggregate);

export default app;
The convex.config.ts file should be in your convex/ folder, not at the project root.
3

Deploy the component

Run your Convex development server to deploy the component:
npx convex dev
The component will be installed and ready to use in your Convex functions.

​
Using Multiple Aggregates

If you need to aggregate multiple tables or use different sorting strategies, register the component multiple times with unique names:
convex/convex.config.ts
import { defineApp } from "convex/server";
import aggregate from "@convex-dev/aggregate/convex.config";

const app = defineApp();

// One aggregate for sorting by score
app.use(aggregate, { name: "aggregateByScore" });

// Another aggregate for grouping by user
app.use(aggregate, { name: "aggregateScoreByUser" });

// Aggregate for photos
app.use(aggregate, { name: "photos" });

export default app;
You’ll reference these named instances when creating TableAggregate objects: 
import { components } from "./_generated/api";

const aggregateByScore = new TableAggregate(components.aggregateByScore, {
  sortKey: (doc) => doc.score,
});

const aggregateScoreByUser = new TableAggregate(components.aggregateScoreByUser, {
  sortKey: (doc) => [doc.username, doc.score],
});
Each aggregate maintains its own internal data structure. Use multiple named aggregates when you need different sorting keys or when aggregating different tables.

​
Verify Installation

To verify the component is installed correctly, check your Convex dashboard at https://dashboard.convex.dev. You should see the aggregate component listed under your project’s components.

​
Next Steps

Quickstart

Build your first aggregate in minutes

API Reference

Explore all available methods and options

Build docs developers (and LLMs) love

Get started for freeTalk to us