Convex Adapter

The Convex adapter stores your content schema in a Convex database, providing real-time sync and reactive updates. This adapter powers the ACMS SaaS platform.

Installation

npm install @useacms/cli

Configuration

import { defineConfig } from '@useacms/client';
import { localFile, convex } from '@useacms/cli/adapters';

export default defineConfig({
  dev: localFile({ path: './acms.json' }),
  production: convex({
    deploymentUrl: process.env.CONVEX_URL,
    projectId: process.env.ACMS_PROJECT_ID,
  }),
});

Options

Option	Type	Required	Description
deploymentUrl	string	Yes	Convex deployment URL
projectId	string	Yes	ACMS project ID in the Convex database

Setup

1. Set Up a Convex Project

If you’re self-hosting the ACMS backend:

npx convex init
npx convex dev

2. Configure Environment Variables

.env

CONVEX_URL=https://your-deployment.convex.cloud
ACMS_PROJECT_ID=your_project_id

Usage

acms push    # Upload to Convex
acms pull    # Download from Convex
acms sync    # Bi-directional sync

How It Works

• Read: Queries the Convex database for the project’s schema.
• Write: Mutates the Convex database with the updated schema.
• Watch: Subscribes to real-time updates via Convex’s reactive system.

Convex provides real-time subscriptions, so changes made in the dashboard or by other users are propagated instantly.

Real-Time Sync

Unlike other adapters that require polling or manual sync, the Convex adapter supports real-time subscriptions:

import { acms, subscribe } from '@useacms/client';

// Content updates automatically when changed in the database
subscribe(() => {
  console.log('Content updated:', acms.hero.title);
});

Use Cases

• ACMS SaaS platform — The hosted platform uses Convex as its backend.
• Real-time collaboration — Multiple editors see changes instantly.
• Multi-tenant applications — Convex supports per-project isolation.
• Reactive applications — Best for apps that need live content updates.

SaaS Platform

The Convex adapter is the foundation of the ACMS hosted SaaS platform. When using the SaaS platform, you don’t need to configure Convex directly — the platform handles infrastructure, authentication, and project management.

See Hosted SaaS for more information.

Limitations

• Requires a Convex account and deployment.
• Self-hosting requires running a Convex backend.
• Database size limits depend on your Convex plan.

Next Steps

• Learn about the Hosted SaaS platform
• Explore other adapters: GitHub, Vercel Edge Config