Convex Panel Documentation

Introduction

Convex Panel is a development tool for Convex applications that provides real-time logs, data inspection, and more. It helps developers monitor and debug their Convex applications with a beautiful, intuitive interface.

NPM Version: convex-panel

Features

Real-time Data View: Browse and filter your Convex tables with ease
Live Logs: Monitor function calls, HTTP actions, and system events in real-time
Advanced Filtering: Filter logs and data with query capabilities
Health Monitoring: Track the health of your application with metrics for cache rates, scheduler health, database performance, and system latency
In-place Data Editing: Directly edit your data values with double-click editing capability
Beautiful UI: Sleek, developer-friendly interface that integrates with your app
Automatic Token Setup: Automatically configures your Convex access token during installation

Installation

# Using npm 
npm install convex-panel

# Using yarn
yarn add convex-panel

# Using pnpm
pnpm add convex-panel

# Using bun
bun add convex-panel

During installation, the package will automatically:

Check if you're logged in to Convex
If not logged in, prompt you to run npx convex login
Once logged in, detect your Convex access token from ~/.convex/config.json (or %USERPROFILE%\.convex\config.json on Windows)
Add it to your project's .env file as CONVEX_ACCESS_TOKEN

Usage

You can use the panel in two ways:

Automatic Token Setup (Recommended): The access token will be automatically loaded from your environment variables during installation.

Manual Token Setup: If you prefer, you can manually provide the access token by running:

# On macOS/Linux
cat ~/.convex/config.json

# On Windows
more %USERPROFILE%\.convex\config.json

Warning: The ConvexPanel component must be placed inside a ConvexProvider or ConvexReactProvider component.

Example Usage

import { ConvexPanel } from 'convex-panel';
import { ConvexReactClient } from "convex/react";

export default function YourComponent() {
  const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL);

  return (
    <>
      {/* Your app content */}
      <ConvexPanel
        accessToken="YOUR_ACCESS_TOKEN"
        deployKey={process.env.CONVEX_DEPLOYMENT}
        convex={convex}
      />
    </>
  );
}

Configuration

The Convex Panel accepts the following props:

Prop	Type	Required	Description
accessToken	string	Yes	Your Convex access token (from convex config)
deployKey	string	Yes	Your Convex deployment URL (or use CONVEX_DEPLOYMENT env var)
deployUrl	string	No	Alternative to deployKey - your Convex deployment URL
convex	ConvexReactClient	Yes	Convex client instance
theme	ThemeClasses	No	Custom theme options
initialLimit	number	No	Initial log limit (default: 100)
initialShowSuccess	boolean	No	Initially show success logs (default: true)
initialLogType	LogType	No	Initial log type filter (default: ALL)
maxStoredLogs	number	No	Maximum number of logs to store (default: 500)
onLogFetch	(logs: LogEntry[]) => void	No	Callback function when logs are fetched
onError	(error: string) => void	No	Callback function when an error occurs
onToggle	(isOpen: boolean) => void	No	Callback function when panel is opened/closed
buttonPosition	'bottom-left' \| 'bottom-center' \| 'bottom-right' \| 'right-center' \| 'top-right'	No	Position of the ConvexPanel button (default: bottom-right)
useMockData	boolean	No	Whether to use mock data instead of real API data (default: false)

Troubleshooting

Common Errors

"Convex authentication required"

Make sure you've provided a valid access token via the accessToken prop
Get your access token by running cat ~/.convex/config.json or more %USERPROFILE%\.convex\config.json

No logs appearing

Verify that your deployKey prop or CONVEX_DEPLOYMENT environment variable is correctly set
Check that you've passed the convex prop to the ConvexPanel component
Verify that your access token is valid

Build warnings about "use client" directive

If you see warnings like Module level directives cause errors when bundled, "use client" in "src/data/components/FilterMenu.tsx" was ignored, this is expected and won't affect functionality. The package is designed to work in both client and server environments.