Velt CLI - Velt

Add Velt real-time collaboration to an existing Next.js project from your terminal. The CLI installs dependencies, generates components, and auto-wires VeltProvider into your app layout. No manual configuration required.

GitHub Repository

velt-js/add-velt-next-js

When to Use the CLI

You want to add Velt to a Next.js project quickly from the command line
You prefer a non-interactive, flag-driven workflow
You want to scaffold specific features (comments, notifications, CRDT) in one step
You are setting up Velt without an AI coding assistant

If you are using an AI coding agent like Claude Code or Cursor, see the MCP Installer for an AI-assisted setup experience.

Prerequisites

Node.js 18+
Next.js 13.4.0+ (App Router or Pages Router)
React 18.2.0+
Package manager: npm, yarn, or pnpm
A Velt API key

Quickstart

Run the CLI in your Next.js project directory:

npx @velt-js/add-velt

This installs the baseline Velt SDK (@veltdev/react, @veltdev/types) and generates core components. To include specific features, add flags:

npx @velt-js/add-velt --comments

After the CLI completes, set your API key in .env.local:

NEXT_PUBLIC_VELT_API_KEY=your_api_key_here

Then update the generated files with your app-specific logic:

components/velt/VeltInitializeDocument.tsx: replace the placeholder document ID with your own (e.g., from a route parameter)
components/velt/VeltInitializeUser.tsx: replace the placeholder user object with your real user context

Start your dev server and verify Velt loads in the browser console.

Configuration

API Key

The CLI wires VeltProvider to read your API key from the NEXT_PUBLIC_VELT_API_KEY environment variable. Add it to .env.local:

NEXT_PUBLIC_VELT_API_KEY=your_api_key_here

Get your API key from the Velt Console.

Document ID

Update components/velt/VeltInitializeDocument.tsx with your document ID source:

// Replace with your document ID logic
const documentId = 'your-document-id';
const documentName = 'your-document-name';

User Authentication

Update components/velt/VeltInitializeUser.tsx with your user retrieval logic:

// Replace with your user retrieval logic
const user = {
  userId: 'user-id',
  organizationId: 'organization-id',
  email: 'user@example.com',
};

Options

Feature Flags

Flag	Description
`--comments`	Add inline comments (VeltComments, VeltCommentsSidebar, VeltCursor)
`--notifications`	Add notifications (VeltNotificationsTool, VeltCursor)
`--presence`	Add presence indicators (VeltPresence)
`--cursors`	Add live cursors (VeltCursor)

The CLI supports core scaffolding features. For additional features like Recorder, Single Editor Mode, Self-Hosting Data, Activity Logs, and Huddle, use the MCP Installer with an AI coding agent.

CRDT Type Flags (choose one)

Flag	Description
`--reactflow-crdt`	Canvas collaboration with ReactFlow
`--tiptap-crdt`	Rich text editor collaboration with Tiptap
`--codemirror-crdt`	Code editor collaboration with CodeMirror

Combined Flag

Flag	Description
`--all`	Enable comments + notifications + CRDT (requires a CRDT type flag)

Installation Flags

Flag	Description
`--force`, `-f`	Force overwrite existing files
`--legacy-peer-deps`	Use legacy peer deps (npm only)
`--help`, `-h`	Show help message

What the CLI Does

The CLI performs these steps automatically:

Detects your project: finds next.config.js/next.config.ts, determines App Router vs Pages Router, and identifies your package manager (npm, yarn, or pnpm with workspace support)
Installs dependencies: adds @veltdev/react and @veltdev/types, plus feature-specific packages (e.g., yjs for CRDT)
Generates components: creates files under components/velt/ for collaboration, document initialization, and user authentication
Copies assets: adds icon SVGs to public/icons/ when features like notifications are selected

After the CLI completes, you need to manually wrap your page content with VeltProvider. The CLI skips auto-wiring the layout if it detects a metadata export (server component). See the Troubleshooting section for the required code.

Generated Files

Core (always created)

components/velt/
├── VeltCollaboration.tsx       # Main collaboration wrapper
├── VeltInitializeDocument.tsx  # Document initialization hook
└── VeltInitializeUser.tsx      # User authentication hook

With features enabled

When you use --comments, --notifications, or CRDT flags, the CLI also generates:

components/velt/
├── VeltTools.tsx               # Toolbar (presence, sidebar, notifications)
└── ui-customization/
    ├── VeltCustomization.tsx   # Dark mode + wireframe wrapper
    ├── styles.css              # Custom styles
    └── ...                     # Feature-specific wireframe files

To use the toolbar components, import VeltTools into your page:

import VeltTools from '@/components/velt/VeltTools';

export default function MyPage() {
  return (
    <>
      <div className="toolbar">
        <VeltTools />
      </div>
      {/* Your page content */}
    </>
  );
}

Examples

# Core only (minimal setup)
npx @velt-js/add-velt

# Comments only (includes Presence + Cursors)
npx @velt-js/add-velt --comments

# Notifications only (includes Presence + Cursors)
npx @velt-js/add-velt --notifications

# Comments + Notifications
npx @velt-js/add-velt --comments --notifications

# All features with ReactFlow CRDT
npx @velt-js/add-velt --all --reactflow-crdt

# All features with Tiptap CRDT
npx @velt-js/add-velt --all --tiptap-crdt

# Force overwrite existing files
npx @velt-js/add-velt --all --reactflow-crdt --force

Troubleshooting

Dependency conflicts

If installation fails due to peer dependency issues:

npx @velt-js/add-velt --force
# or (npm only)
npx @velt-js/add-velt --legacy-peer-deps

The CLI uses a smart retry strategy that automatically tries --force and --legacy-peer-deps as fallbacks.

Existing files

Use --force to overwrite previously generated files:

npx @velt-js/add-velt --comments --force

Multiple CRDT types

Only one CRDT type can be selected at a time:

# Wrong — will error
npx @velt-js/add-velt --reactflow-crdt --tiptap-crdt

# Correct
npx @velt-js/add-velt --reactflow-crdt

`--all` without a CRDT type

The --all flag requires a CRDT type:

# Wrong — will error
npx @velt-js/add-velt --all

# Correct
npx @velt-js/add-velt --all --reactflow-crdt

Manual VeltProvider setup

After running the CLI, wrap your page content with VeltProvider in the page where collaboration happens (NOT in layout.tsx):

// app/dashboard/[docId]/page.tsx (or your collaboration page)
"use client";
import { VeltProvider } from '@veltdev/react';
import { useVeltAuthProvider } from '@/components/velt/VeltInitializeUser';
import { VeltCollaboration } from '@/components/velt/VeltCollaboration';

export default function DocumentPage() {
  const { authProvider } = useVeltAuthProvider();
  return (
    <VeltProvider apiKey={process.env.NEXT_PUBLIC_VELT_API_KEY!} authProvider={authProvider}>
      <VeltCollaboration documentId={docId} />
      {/* Your page content */}
    </VeltProvider>
  );
}

Do NOT place VeltProvider in app/layout.tsx. If your layout exports metadata (a server-only feature), adding VeltProvider there requires "use client" which conflicts with the metadata export. Place VeltProvider in the specific page where collaboration features are needed.

Next Steps

Quickstart: Manual step-by-step Velt setup (without the CLI)
Agent Skills: Teach your AI coding agent correct Velt patterns
MCP Installer: AI-assisted Velt installation through MCP
Comments Overview: Learn about commenting features
CRDT Setup: Set up collaborative editing
Key Concepts: Understand documents, locations, users, and access control

GitHub Repository

​When to Use the CLI

​Prerequisites

​Quickstart

​Configuration

​API Key

​Document ID

​User Authentication

​Options

​Feature Flags

​CRDT Type Flags (choose one)

​Combined Flag

​Installation Flags

​What the CLI Does

​Generated Files

​Core (always created)

​With features enabled

​Examples

​Troubleshooting

​Dependency conflicts

​Existing files

​Multiple CRDT types

​--all without a CRDT type

​Manual VeltProvider setup

​Next Steps

When to Use the CLI

Prerequisites

Quickstart

Configuration

API Key

Document ID

User Authentication

Options

Feature Flags

CRDT Type Flags (choose one)

Combined Flag

Installation Flags

What the CLI Does

Generated Files

Core (always created)

With features enabled

Examples

Troubleshooting

Dependency conflicts

Existing files

Multiple CRDT types

`--all` without a CRDT type

Manual VeltProvider setup

Next Steps