Convex

Reactive backend-as-a-service with a built-in TypeScript-native database, real-time queries, and zero-config deployment.

Overview

Convex is a backend-as-a-service that replaces a separate API server and database. It provides TypeScript-native queries and mutations that run on Convex's cloud, with real-time reactivity out of the box.

Selecting Convex as your backend automatically selects the Convex database as well.

Scaffolded Structure

convex/
  _generated/        # Auto-generated by `npx convex dev` (do not edit)
  http.ts            # HTTP actions for webhooks / external integrations
  schema.ts          # Database schema definition
convex.json          # Convex project config

Setup

Create a project at dashboard.convex.dev
Add your deployment URL to .env.local:

NEXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud

Run the Convex dev server alongside Next.js:

pnpm dev
# or start separately:
npx convex dev

Connecting to Next.js

The scaffolded app/layout.tsx wraps the app with ConvexProvider:

import { ConvexProvider, ConvexReactClient } from 'convex/react'

const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL!)

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <ConvexProvider client={convex}>{children}</ConvexProvider>
      </body>
    </html>
  )
}

Writing Queries and Mutations

Define functions in convex/:

// convex/tasks.ts
import { query, mutation } from './_generated/server'
import { v } from 'convex/values'

export const list = query({
  args: {},
  handler: async (ctx) => {
    return await ctx.db.query('tasks').collect()
  },
})

export const create = mutation({
  args: { text: v.string() },
  handler: async (ctx, { text }) => {
    return await ctx.db.insert('tasks', { text })
  },
})

Use them in React components:

import { useQuery, useMutation } from 'convex/react'
import { api } from '@/convex/_generated/api'

const tasks = useQuery(api.tasks.list)
const createTask = useMutation(api.tasks.create)

Compatibility

✅ Works with: Next.js, Clerk, Better Auth, Resend, shadcn/ui
❌ Convex DB requires the Convex backend — cannot be used with Hono