`add`

Add VexBlocks packages to your project

Usage

npx @vexblocks/cli add [packages...] [options]

Description

The add command downloads and installs VexBlocks packages from the official repository into your Turborepo project. It handles dependencies automatically and can merge with existing Convex backends.

Available Packages

Package	Description	Install Path
`cms`	CMS Dashboard (Next.js app)	`apps/cms`
`backend`	Convex backend with CMS functions	`packages/backend`
`shared`	Shared utilities and components	`packages/cms-shared`
`types`	Type generator for schemas	`packages/type-generator`
`all`	All packages above	-

How It Works

Validate Project

Checks that you're in a Turborepo project by looking for turbo.json.

Resolve Dependencies

Automatically includes required dependencies. For example, adding cms will also add backend and shared.

Check for Conflicts

Prompts you if packages already exist, offering to overwrite or skip.

Download & Install

Downloads the latest version from GitHub and extracts to the appropriate directories.

Update Manifest

Records installed packages in vexblocks.json for tracking.

Options

Option	Type	Description
`--yes`, `-y`	boolean	Skip all prompts and overwrite existing files
`--overwrite`	boolean	Overwrite existing packages without prompting
`--cwd`	string	Working directory for the command

Examples

Add All Packages

npx @vexblocks/cli add all

This installs the CMS dashboard, backend, shared utilities, and type generator.

Add Specific Packages

npx @vexblocks/cli add cms backend

Installs only the CMS and backend packages (plus their dependencies).

Interactive Selection

npx @vexblocks/cli add

Running without arguments shows an interactive checkbox to select packages.

Force Overwrite

npx @vexblocks/cli add all --overwrite

Overwrites existing packages without prompting.

Package Dependencies

Some packages have dependencies that are automatically included:

cms requires backend and shared
types requires backend

The CLI will automatically inform you when additional packages are added to satisfy dependencies.

Existing Convex Backend

If you already have a Convex project with a schema.ts file, the CLI will:

Download only CMS-specific files (convex/cms, schema.cms.ts, etc.)
Automatically merge CMS tables into your schema by adding ...cmsSchemaExports

Already have a users table? The CMS includes a users table. If you already have one, use cmsTablesWithoutUsers and extend your existing users table with cmsUserFields.

// Option 1: No existing users table
import { defineSchema } from "convex/server"
import { cmsSchemaExports } from "./cms/schema.cms"

export default defineSchema({
  // VexBlocks CMS tables (includes users)
  ...cmsSchemaExports,

  // Your existing tables
  products: defineTable({ ... }),
})

// Option 2: With existing users table
import { defineSchema, defineTable } from "convex/server"
import { cmsTablesWithoutUsers, cmsUserFields } from "./cms/schema.cms"

const users = defineTable({
  ...cmsUserFields,  // Required CMS fields
  companyId: v.id("companies"),  // Your custom fields
})
  .index("email", ["email"])
  .index("authId", ["authId"])
  .index("by_role", ["role"])
  .index("by_active", ["isActive"])

export default defineSchema({
  users,
  ...cmsTablesWithoutUsers,
  products: defineTable({ ... }),
})

Smart Merging: The CLI detects existing schemas and merges safely without overwriting your custom tables.

Protected Files

The following files are protected and will never be overwritten:

packages/backend/convex/cms/vexblocks.config.ts - Your CMS configuration
packages/backend/.env - Environment variables
packages/backend/.env.local - Local environment overrides
packages/cms-shared/src/types/generated.ts - Your generated types
packages/backend/emails/*.ts - Your customized email templates

Smart package.json Merging

The CLI intelligently merges the backend package.json:

Preserves your package name and version
Adds required VexBlocks dependencies
Updates VexBlocks scripts (dev, build, etc.)
Keeps your custom fields and configurations

This means you can have a backend named my-app-backend and the CLI will preserve that name while adding the necessary VexBlocks dependencies.

Important: Your custom schema types in generated.ts are preserved to prevent loss of your content structure definitions.

After Installation

Once packages are installed, you should:

Install dependencies: pnpm install
Configure VexBlocks settings in packages/backend/convex/cms/vexblocks.config.ts (set your app name and email settings)
Configure environment variables in .env
Set up Convex: npx convex dev in packages/backend
Start development: pnpm dev

add