Install and run teams

Install the component in your Convex application:

npm install @clipin/convex-teams@1.0.0

Use Convex >=1.43.0 <2.0.0. The invitation dependency installs automatically. Mount teams with the configuration below, then run npx convex dev in your application to generate its component API.

To run the repository example, use Node.js 22 or later and Bun 1.4.0.

1. Get the source

git clone https://github.com/clipinfit/convex-teams.git
cd convex-teams
bun install --frozen-lockfile
bun run build

The component is in packages/convex-teams. The host example is in packages/example-backend. The website is in apps/web.

2. Start the example backend

bun run dev:example

The example starts an anonymous local Convex deployment. It does not connect to production data.

From another terminal, check the workspace:

bun run typecheck
bun run test
bun run lint
bun run pack:check

3. Run the concurrency proofs

cd packages/example-backend
bunx convex run proof:run
bunx convex run proof:concurrentBootstrap
bunx convex run proof:concurrentDuplicateGrant
bunx convex run proof:largeSeatLimit
bunx convex run proof:concurrentSlugs
bunx convex run migrationProof:run
bunx convex run migrationProof:runLifecycle

The seat proof must return one successful grant, one rejected grant, and two members. The bootstrap proof must create one personal team. The duplicate grant proof must create one membership for the recipient. The large-limit proof must return two members. The slug proof must return two distinct slugs within the length limit. The import proof checks two synthetic teams. The lifecycle proof completes without error after preference translation, removal fallback, invitation acceptance, ownership transfer, and deletion.

How the example mounts teams

import { defineApp } from "convex/server";
import teams from "@clipin/convex-teams/convex.config.js";

const app = defineApp();
app.use(teams);
export default app;

Create a client in your host functions:

import { TeamsClient } from "@clipin/convex-teams";
import { components } from "./_generated/api.js";

export const teams = new TeamsClient(components.teams);

Inside a host mutation, derive the actor from authentication:

const identity = await ctx.auth.getUserIdentity();
if (!identity) throw new Error("Not authorized.");

return teams.createTeam(ctx, identity.subject, "Studio workspace");

See the complete host example for recipient verification and delivery. Read the host contract before exposing a client method.

Run the docs website

From the repository root:

bun run dev:web

Open http://localhost:3000.