@velt-js/add-velt

CLI tool to add Velt real-time collaboration to your Next.js application.

Features

• Smart Project Analysis: Automatically detects your project structure and package manager
• Workspace Support: Detects pnpm/yarn workspaces by checking parent directories
• Feature Flags: Choose specific features (comments, notifications, CRDT types)
• Auto-Wiring: Automatically configures VeltProvider and VeltCollaboration in your app layout
• Strict Scoping: Only installs dependencies and scaffolds files for selected features
• Zero Config: Works out of the box with App Router and Pages Router
• Velt SDK v4.x.x: Installs Velt SDK v4.x.x packages

Installation

npx @velt-js/add-velt

Or install globally:

npm install -g @velt-js/add-velt
add-velt

Quick Start

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

# Add comments feature
npx @velt-js/add-velt --comments

# Add notifications feature
npx @velt-js/add-velt --notifications

# Add CRDT for ReactFlow canvas
npx @velt-js/add-velt --reactflow-crdt

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

Command Reference

npx @velt-js/add-velt [options]

Feature Flags

| Flag | Description | |------|-------------| | --comments | Add comments (VeltComments, VeltCommentsSidebar, VeltCursor) | | --notifications | Add notifications (VeltNotificationsTool, VeltCursor) |

CRDT Type Flags (choose one)

| Flag | Description | Documentation | |------|-------------|---------------| | --reactflow-crdt | Add ReactFlow CRDT (canvas collaboration) | ReactFlow CRDT Docs | | --tiptap-crdt | Add Tiptap CRDT (rich text editor) | Tiptap CRDT Docs | | --codemirror-crdt | Add CodeMirror CRDT (code editor) | CodeMirror CRDT Docs |

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 |

Feature Documentation

Comments

What it does: Enables inline commenting on any element in your app. Users can click to add comments, reply to threads, and view all comments in a sidebar.

Documentation: Comments Overview

Flags: --comments or included with --all

Components generated:

• VeltCollaboration.tsx - Renders VeltComments, VeltCommentsSidebar, and VeltCursor
• VeltTools.tsx - Renders VeltPresence and VeltSidebarButton

Code injected:

// In VeltCollaboration.tsx
<VeltComments
  popoverMode={true}
  shadowDom={false}
  textMode={false}
  commentPinHighlighter={false}
  dialogOnHover={false}
/>
<VeltCommentsSidebar groupConfig={{ enable: false }} />
<VeltCursor />

UI Customization files:

• VeltCommentBubbleWf.tsx - Custom comment bubble wireframe
• VeltCommentToolWf.tsx - Custom comment tool wireframe
• styles.css - Custom styling

Notifications

What it does: Adds a notification system that alerts users to comments, mentions, and other collaboration events.

Documentation: Notifications Setup

Flags: --notifications or included with --all

Components generated:

• VeltCollaboration.tsx - Renders VeltCursor
• VeltTools.tsx - Renders VeltPresence and VeltNotificationsTool

Code injected:

// In VeltTools.tsx
<VeltNotificationsTool
  settings={true}
  shadowDom={false}
  tabConfig={{
    forYou: { name: "For You", enable: true },
    documents: { name: "Documents", enable: true },
    all: { name: "All", enable: true },
  }}
/>

UI Customization files:

• VeltNotificationsToolWf.tsx - Custom notifications wireframe
• styles.css - Custom styling

Presence

What it does: Shows which users are currently online/active in the document. Displays user avatars and status indicators.

Documentation: Presence Setup

Flags: Automatically included with --comments, --notifications, or any CRDT flag

Component generated:

• VeltTools.tsx - Contains VeltPresence

Code injected:

// In VeltTools.tsx
<VeltPresence />

Placement: Render <VeltTools /> in your toolbar or header area to display the presence indicators.

Cursors

What it does: Shows live cursor positions of other users in real-time. Users can see where others are pointing/working.

Documentation: Cursors Setup

Flags: Automatically included with --comments, --notifications, or any CRDT flag

Component generated:

• VeltCollaboration.tsx - Contains VeltCursor

Code injected:

// In VeltCollaboration.tsx
<VeltCursor />

Placement: The <VeltCursor /> component is rendered inside <VeltCollaboration /> which is auto-wired into your app layout. Cursors appear automatically across your app.

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

# ReactFlow CRDT only (includes Presence + Cursors)
npx @velt-js/add-velt --reactflow-crdt

# Tiptap CRDT only (includes Presence + Cursors)
npx @velt-js/add-velt --tiptap-crdt

# CodeMirror CRDT only (includes Presence + Cursors)
npx @velt-js/add-velt --codemirror-crdt

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

# Comments + Tiptap CRDT (includes Presence + Cursors)
npx @velt-js/add-velt --comments --tiptap-crdt

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

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

# All features with CodeMirror
npx @velt-js/add-velt --all --codemirror-crdt

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

Dependencies Installed

Velt SDK packages are installed at v4.x.x. Third-party dependencies use their latest versions.

Baseline (always)

| Package | Type | |---------|------| | @veltdev/react | Production | | @veltdev/types | Development |

ReactFlow CRDT (--reactflow-crdt)

| Package | Type | |---------|------| | @veltdev/reactflow-crdt | Production | | yjs | Production |

Tiptap CRDT (--tiptap-crdt)

| Package | Type | |---------|------| | @veltdev/tiptap-crdt | Production | | @veltdev/tiptap-crdt-react | Production | | @veltdev/tiptap-velt-comments | Production | | yjs | Production | | y-prosemirror | Production |

CodeMirror CRDT (--codemirror-crdt)

| Package | Type | |---------|------| | @veltdev/codemirror-crdt | Production | | @veltdev/codemirror-crdt-react | Production | | yjs | Production | | y-codemirror.next | Production |

Files Generated

Core (always created)

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

With --comments

components/velt/
├── VeltTools.tsx               # Toolbar (VeltPresence, VeltSidebarButton)
└── ui-customization/
    ├── VeltCustomization.tsx   # Dark mode + wireframe wrapper
    ├── VeltCommentBubbleWf.tsx # Comment bubble wireframe
    ├── VeltCommentToolWf.tsx   # Comment tool wireframe
    └── styles.css              # Custom styles

With --notifications

components/velt/
├── VeltTools.tsx               # Toolbar (VeltPresence, VeltNotificationsTool)
└── ui-customization/
    ├── VeltCustomization.tsx   # Dark mode + wireframe wrapper
    ├── VeltNotificationsToolWf.tsx # Notifications wireframe
    └── styles.css              # Custom styles

With --comments --notifications

components/velt/
├── VeltTools.tsx               # Full toolbar
└── ui-customization/
    ├── VeltCustomization.tsx
    ├── VeltCommentBubbleWf.tsx
    ├── VeltCommentToolWf.tsx
    ├── VeltNotificationsToolWf.tsx
    ├── VeltSidebarButtonWf.tsx
    └── styles.css

With CRDT flags or --all

components/velt/
├── VeltTools.tsx               # Full toolbar (+ VeltHuddleTool for ReactFlow)
└── ui-customization/
    ├── VeltCustomization.tsx
    ├── VeltCommentBubbleWf.tsx
    ├── VeltCommentToolWf.tsx
    ├── VeltNotificationsToolWf.tsx
    ├── VeltSidebarButtonWf.tsx
    └── styles.css

Auto-Wiring

The CLI automatically modifies your app layout to include VeltProvider and VeltCollaboration:

App Router (app/layout.tsx):

• Adds imports for VeltProvider, useVeltAuthProvider, and VeltCollaboration
• Creates a VeltClientWrapper component
• Wraps {children} with the wrapper inside <body>

Pages Router (pages/_app.tsx):

• Adds the same imports
• Wraps <Component {...pageProps} /> with VeltClientWrapper

The auto-wiring is idempotent - running the CLI again won't duplicate the wiring.

Strict Scoping Rules

The CLI enforces strict scoping to avoid installing unnecessary dependencies or files:

• --comments only: No notifications wireframes included
• --notifications only: No comment wireframes included
• CRDT types: Only ONE can be selected at a time
• --all: REQUIRES a CRDT type flag

Setup After Installation

1. Get Your API Key

Get your API key from Velt Console.

2. Configure API Key

After running the CLI, update your API key in the auto-wired layout:

// In app/layout.tsx (auto-generated VeltClientWrapper)
<VeltProvider apiKey={process.env.NEXT_PUBLIC_VELT_API_KEY || 'YOUR_API_KEY'} authProvider={authProvider}>

Or set NEXT_PUBLIC_VELT_API_KEY in your .env.local file.

3. Configure 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';

4. Configure User Authentication

Update components/velt/VeltInitializeUser.tsx with your user context:

// Replace with your user retrieval logic
const user = {
  userId: 'user-id',
  organizationId: 'organization-id',
  email: '[email protected]',
};

5. Add VeltTools (if using features)

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

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

6. CRDT-Specific Setup

For CRDT integrations, see the relevant documentation:

• ReactFlow: https://docs.velt.dev/realtime-collaboration/crdt/setup/reactflow
• Tiptap: https://docs.velt.dev/realtime-collaboration/crdt/setup/tiptap
• CodeMirror: https://docs.velt.dev/realtime-collaboration/crdt/setup/codemirror

Troubleshooting

Dependency Conflicts

npx @velt-js/add-velt --force
# or
npx @velt-js/add-velt --legacy-peer-deps

Existing Files

Use --force to overwrite:

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

Multiple CRDT Types Error

Only one CRDT type can be selected:

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

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

--all Without CRDT Type Error

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

Auto-Wiring Failed

If no layout file was found, manually wrap your app:

// app/layout.tsx
import { VeltProvider } from '@veltdev/react';
import { useVeltAuthProvider } from '@/components/velt/VeltInitializeUser';
import { VeltCollaboration } from '@/components/velt/VeltCollaboration';

function VeltClientWrapper({ children }: { children: React.ReactNode }) {
  const { authProvider } = useVeltAuthProvider();
  return (
    <VeltProvider apiKey="YOUR_API_KEY" authProvider={authProvider}>
      <VeltCollaboration />
      {children}
    </VeltProvider>
  );
}

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <VeltClientWrapper>{children}</VeltClientWrapper>
      </body>
    </html>
  );
}

Version Compatibility

• Next.js: 13.4.0+
• React: 18.2.0+
• TypeScript: 5.0.0+
• Node.js: 18+

Support

• Velt Documentation
• Velt Console