@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

``bash
npx @velt-js/add-velt
`

Or install globally:

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

Quick Start

`bash


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

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

$3

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

$3

| 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 |

$3

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

$3

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

---

Feature Documentation

$3

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:
`tsx
// In VeltCollaboration.tsx
popoverMode={true}
shadowDom={false}
textMode={false}
commentPinHighlighter={false}
dialogOnHover={false}
/>


`

UI Customization files:
- VeltCommentBubbleWf.tsx - Custom comment bubble wireframe
- VeltCommentToolWf.tsx - Custom comment tool wireframe
- styles.css - Custom styling

---

$3

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:
`tsx
// In VeltTools.tsx
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

---

$3

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:
`tsx
// In VeltTools.tsx

`

Placement: Render in your toolbar or header area to display the presence indicators.

---

$3

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:
`tsx
// In VeltCollaboration.tsx

`

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

---

Examples

`bash


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.

$3

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

$3

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

$3

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

$3

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

Files Generated

$3

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

$3

`
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
`

$3

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

$3

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

$3

`
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

Pages Router (pages/_app.tsx):
- Adds the same imports
- Wraps 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

$3

Get your API key from Velt Console.

$3

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

`tsx
// In app/layout.tsx (auto-generated VeltClientWrapper)

`

Or set NEXT_PUBLIC_VELT_API_KEY in your .env.local file.

$3

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

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

$3

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

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

$3

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

export default function MyPage() {
return (
<>



{/ Your page content /}

);
}
`

$3

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

$3

`bash
npx @velt-js/add-velt --force


or


npx @velt-js/add-velt --legacy-peer-deps
`

$3

Use --force to overwrite:

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

$3

Only one CRDT type can be selected:

`bash


Wrong - will error

npx @velt-js/add-velt --reactflow-crdt --tiptap-crdt

Correct

npx @velt-js/add-velt --reactflow-crdt
`

$3

The --all flag requires a CRDT type:

`bash


Wrong - will error

npx @velt-js/add-velt --all

Correct

npx @velt-js/add-velt --all --reactflow-crdt
`

$3

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

`tsx
// 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 (


{children}

);
}

export default function RootLayout({ children }: { children: React.ReactNode }) {
return (


{children}


);
}
``

Version Compatibility

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

Support

- Velt Documentation
- Velt Console