---
name: bijection-convex-livekit
description: "Evaluate and integrate the Convex LiveKit component with Bijection."
---

# Convex LiveKit

Sync LiveKit rooms, participants, and egress into Convex reactively. Create rooms and mint access tokens from Convex functions.

This is an upstream package. It has not been adapted or qualified for Bijection.

- Package: convex-livekit
- Source: https://github.com/sholajegede/convex-livekit
- npm: https://www.npmjs.com/package/convex-livekit
- Directory: https://bijection.com/components/convex-livekit

Read the upstream README for setup, license, and compatibility before using it.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes convex-livekit. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


> Agents: read this skill fully before writing code that uses Convex LiveKit. Follow the installation and configuration steps exactly.

# Convex LiveKit

## Instructions

convex-livekit syncs LiveKit room, participant, and egress state into Convex tables via verified webhooks, making that data available to reactive queries. It also provides Convex actions for room management (create, delete, update metadata, remove participants) and JWT token minting for client authentication. The component's tables are isolated in their own schema and are only accessible through the functions the component exposes.

### Installation

```bash
npm install convex-livekit
```

Current npm version: `convex-livekit@0.0.9`

## Use cases

- Building a live audio or video app where the UI needs to reactively reflect who is in a room without polling, using useQuery against synced participant and room data
- Generating room-join access tokens from a Convex action or query rather than running a separate token service
- Displaying recording or streaming status live by tracking egress state (started, updated, ended) as webhook events arrive
- Kicking or removing participants from a room server-side from a Convex action in response to app logic
- Showing room presence indicators or participant counts that update in real time as users join and leave LiveKit rooms

## How it works

The component is registered in convex.config.ts using app.use(convexLivekit), which provisions isolated tables for rooms, participants, egress jobs, and webhook events. A LiveKit client instance is created by passing components.convexLivekit along with your LIVEKIT_API_KEY, LIVEKIT_API_SECRET, and LIVEKIT_HOST environment variables. This instance is used across your Convex functions to call room management actions and queries.

Inbound webhook events from LiveKit are handled by mounting livekit.webhookHandler as an HTTP action at a route like /webhooks/livekit. Each incoming request is verified by checking the signed JWT (signature, issuer, expiry, and body hash) before any write occurs. Verified events patch or insert rows in the component's tables, so useQuery calls in your React app re-render automatically as rooms open, participants join or leave, and egress jobs change state.

Room management calls like createRoom, deleteRoom, updateRoomMetadata, and removeParticipant are Convex actions that make requests to the LiveKit server API and immediately update the local Convex state, without waiting for the corresponding webhook to arrive. Token minting via createRoomToken is a plain signing method that touches no database and can be called from a query, returning a short-lived JWT the client passes to the LiveKit SDK to connect.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by Convex LiveKit is not needed

## Resources

- [npm package](https://www.npmjs.com/package/convex-livekit)
- [GitHub repository](https://github.com/sholajegede/convex-livekit)
- [Live demo](https://convex-livekit.vercel.app)
- [Convex Components Directory](https://www.convex.dev/components/convex-livekit)
- [Convex documentation](https://docs.convex.dev)