convex

Client for the Convex Cloud

weekly downloads317K

versionv1.32.0

licenseApache-2.0

categorydatabase

convexdatabasereactstateserverless

Overview

Convex is a TypeScript-first backend-as-a-service that eliminates the need for separate state management libraries, ORMs, and realtime synchronization code. It provides a unified SDK where you define database schemas, queries, mutations, and actions in pure TypeScript, with automatic type generation that flows to your frontend. The package includes multiple entry points: convex/server for backend logic, convex/react for React hooks, and convex/browser for non-React applications.

The core value proposition is realtime reactivity without manual cache invalidation. When you use hooks like useQuery, your components automatically re-render when server-side data changes, syncing across all connected clients via WebSockets managed internally. Mutations trigger automatic query invalidation, and all backend functions are strongly typed with autocomplete support. This removes the typical boilerplate of REST endpoints, GraphQL resolvers, or manual subscription management.

Convex is used primarily in React and Next.js applications requiring collaborative or realtime features—think task managers, chat apps, live dashboards, or multiplayer tools. The platform handles deployment, scaling, and data consistency automatically. You write functions in a local convex/ directory, push them with npx convex push, and they become instantly available as typed client-side hooks. Recent versions introduced Convex Components, allowing reusable backend modules with isolated schemas that can be published as npm packages.

The package currently sees 316k weekly downloads and is licensed under Apache-2.0. It's designed for developers who want backend functionality without managing servers, databases, or sync infrastructure, trading hosting flexibility for significant productivity gains in TypeScript-native projects.

Quick Start

typescript

// convex/messages.ts (backend)
import { mutation, query } from './_generated/server';
import { v } from 'convex/values';

export const list = query({
  args: {},
  handler: async (ctx) => {
    return await ctx.db.query('messages')
      .order('desc')
      .take(50);
  },
});

export const send = mutation({
  args: { text: v.string(), author: v.string() },
  handler: async (ctx, args) => {
    await ctx.db.insert('messages', {
      text: args.text,
      author: args.author,
      timestamp: Date.now(),
    });
  },
});

// App.tsx (frontend)
import { useQuery, useMutation } from 'convex/react';
import { api } from './convex/_generated/api';
import { ConvexProvider, ConvexReactClient } from 'convex/react';

const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL);

function Chat() {
  const messages = useQuery(api.messages.list);
  const sendMessage = useMutation(api.messages.send);

  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const form = e.currentTarget;
    const text = form.text.value;
    sendMessage({ text, author: 'User' });
    form.reset();
  };

  return (
    <div>
      {messages?.map((msg, i) => (
        <div key={i}>{msg.author}: {msg.text}</div>
      ))}
      <form onSubmit={handleSubmit}>
        <input name="text" required />
        <button type="submit">Send</button>
      </form>
    </div>
  );
}

export default function App() {
  return (
    <ConvexProvider client={convex}>
      <Chat />
    </ConvexProvider>
  );
}

Use Cases

Collaborative SaaS applications: Build tools like project management boards or document editors where multiple users need to see changes instantly. Convex handles conflict resolution and ensures all clients see consistent state without writing custom WebSocket logic or optimistic update code.

Realtime dashboards and analytics: Create live monitoring interfaces that display continuously updating metrics. Queries automatically re-fetch when underlying data changes, eliminating polling intervals or manual refresh logic while maintaining type safety across data transformations.

Social features and activity feeds: Implement likes, comments, notifications, or presence indicators where user actions need to propagate immediately. Convex mutations can trigger server-side workflows (actions) like sending emails or updating counters atomically with the database write.

Multiplayer games or whiteboards: Synchronize player positions, game state, or drawing strokes across participants in real time. The built-in reactivity ensures all clients render the same state, while scheduled functions (cron jobs) can handle turn timers or cleanup tasks.

Rapid prototyping with authentication: Spin up MVPs with pre-built Auth0 or Clerk integrations from convex/react-auth0 and convex/react-clerk. User sessions and permissions integrate directly with database queries, avoiding separate JWT validation or user table management.

Pros & Cons

Pros

+End-to-end TypeScript with automatic type generation from backend schemas to frontend hooks, eliminating type sync issues
+Realtime subscriptions with zero configuration—no manual WebSocket management, cache invalidation, or optimistic update logic required
+Colocation of backend and frontend code in the same repository with instant deployment via CLI, reducing context switching
+Built-in scheduled functions, file storage, and action workflows for async tasks without separate job queues or Lambda functions
+Convex Components enable modular, reusable backend features with isolated schemas that can be shared across projects as npm packages

Cons

−Vendor lock-in to Convex's hosted platform—no self-hosting option or ability to migrate data to a standard database without custom tooling
−Limited to JavaScript/TypeScript ecosystem; teams using Python, Go, or other backend languages cannot leverage existing Convex infrastructure
−Free tier constraints and usage-based pricing may become expensive at scale compared to self-managed databases or serverless functions
−Smaller ecosystem than Firebase or Supabase for third-party integrations, plugins, or community resources for edge cases
−Query language is TypeScript-based rather than SQL, requiring teams to learn Convex-specific patterns for complex aggregations or joins

Alternatives

apollo-clientv2.6.10

A simple yet functional GraphQL client.

data-fetchingecmascriptes2015

403K / week

@supabase/supabase-jsv2.97.0

Isomorphic Javascript SDK for Supabase

databasejavascripttypescript

10.6M / week

@trpc/serverv11.10.0

The tRPC server library

backend

2.0M / week

Install

bash

npm install convex

bash

pnpm add convex

bash

bun add convex

Overview

Quick Start

typescript

// convex/messages.ts (backend)
import { mutation, query } from './_generated/server';
import { v } from 'convex/values';

export const list = query({
  args: {},
  handler: async (ctx) => {
    return await ctx.db.query('messages')
      .order('desc')
      .take(50);
  },
});

export const send = mutation({
  args: { text: v.string(), author: v.string() },
  handler: async (ctx, args) => {
    await ctx.db.insert('messages', {
      text: args.text,
      author: args.author,
      timestamp: Date.now(),
    });
  },
});

// App.tsx (frontend)
import { useQuery, useMutation } from 'convex/react';
import { api } from './convex/_generated/api';
import { ConvexProvider, ConvexReactClient } from 'convex/react';

const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL);

function Chat() {
  const messages = useQuery(api.messages.list);
  const sendMessage = useMutation(api.messages.send);

  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const form = e.currentTarget;
    const text = form.text.value;
    sendMessage({ text, author: 'User' });
    form.reset();
  };

  return (
    <div>
      {messages?.map((msg, i) => (
        <div key={i}>{msg.author}: {msg.text}</div>
      ))}
      <form onSubmit={handleSubmit}>
        <input name="text" required />
        <button type="submit">Send</button>
      </form>
    </div>
  );
}

export default function App() {
  return (
    <ConvexProvider client={convex}>
      <Chat />
    </ConvexProvider>
  );
}

Use Cases

Pros & Cons

Pros

+End-to-end TypeScript with automatic type generation from backend schemas to frontend hooks, eliminating type sync issues
+Realtime subscriptions with zero configuration—no manual WebSocket management, cache invalidation, or optimistic update logic required
+Colocation of backend and frontend code in the same repository with instant deployment via CLI, reducing context switching
+Built-in scheduled functions, file storage, and action workflows for async tasks without separate job queues or Lambda functions
+Convex Components enable modular, reusable backend features with isolated schemas that can be shared across projects as npm packages

Cons

−Vendor lock-in to Convex's hosted platform—no self-hosting option or ability to migrate data to a standard database without custom tooling
−Limited to JavaScript/TypeScript ecosystem; teams using Python, Go, or other backend languages cannot leverage existing Convex infrastructure
−Free tier constraints and usage-based pricing may become expensive at scale compared to self-managed databases or serverless functions
−Smaller ecosystem than Firebase or Supabase for third-party integrations, plugins, or community resources for edge cases
−Query language is TypeScript-based rather than SQL, requiring teams to learn Convex-specific patterns for complex aggregations or joins