Skip to main content
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:
  1. components/velt/VeltInitializeDocument.tsx: replace the placeholder document ID with your own (e.g., from a route parameter)
  2. 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

FlagDescription
--commentsAdd inline comments (VeltComments, VeltCommentsSidebar, VeltCursor)
--notificationsAdd notifications (VeltNotificationsTool, VeltCursor)
--presenceAdd presence indicators (VeltPresence)
--cursorsAdd live cursors (VeltCursor)

​
CRDT Type Flags (choose one)

FlagDescription
--reactflow-crdtCanvas collaboration with ReactFlow
--tiptap-crdtRich text editor collaboration with Tiptap
--codemirror-crdtCode editor collaboration with CodeMirror

​
Combined Flag

FlagDescription
--allEnable comments + notifications + CRDT (requires a CRDT type flag)

​
Installation Flags

FlagDescription
--force, -fForce overwrite existing files
--legacy-peer-depsUse legacy peer deps (npm only)
--help, -hShow help message

​
What the CLI Does

The CLI performs these steps automatically:
  1. 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)
  2. Installs dependencies: adds @veltdev/react and @veltdev/types, plus feature-specific packages (e.g., yjs for CRDT)
  3. Generates components: creates files under components/velt/ for collaboration, document initialization, and user authentication
  4. 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