add-velt-next-js

🚀 Smart CLI tool to add Velt real-time collaboration features to your existing Next.js application.

Features

• ✅ Smart Project Analysis: Automatically detects your project structure, package manager, and router type
• 🎯 Zero Config: Works out of the box with App Router and Pages Router
• 📦 Intelligent Dependency Management: Handles peer dependency conflicts with multiple fallback strategies
• 🔄 ReactFlow CRDT Support: Optional collaborative canvas with real-time synchronization
• 🎨 UI Customization: Includes Velt Wireframe components for easy customization
• 🔐 Secure Token Generation: Backend route for JWT token generation
• 👥 User Authentication: Demo user system with localStorage persistence
• 🌐 Environment Management: Built-in support for managing API keys and auth tokens

Installation

From npm

npx @veltdev/add-velt add --all

Local Development

cd add-velt-next-js
npm link

Quick Start

Navigate to your existing Next.js project and run:

# Add all Velt features
velt add --all

# Add specific features
velt add --presence --cursor

# Add with environment variables
velt add --all --env --api-key="your_api_key" --auth-token="your_auth_token"

Command Reference

Basic Command

velt add [options]

Options

Feature Flags

• --presence - Add Velt Presence (live avatars)
• --cursor - Add Velt Cursor tracking
• --reactflow-crdt - Add ReactFlow CRDT integration for collaborative canvas
• --all or -all - Add all collaboration features (recommended)
• --shadcn - Include shadcn/ui dependencies

Installation Flags

• --force or -f - Force install and overwrite existing files
• --legacy-peer-deps - Use legacy peer dependencies (npm only, useful for resolving conflicts)

Environment Variable Flags

• --env - Enable environment variable management in .env.local
• --api-key="KEY" - Set NEXT_PUBLIC_VELT_API_KEY value (requires --env)
• --auth-token="TOKEN" - Set VELT_AUTH_TOKEN value (requires --env)

Usage Examples

Minimal Setup

velt add --all

This will:

• Analyze your project structure
• Install all required dependencies
• Generate all Velt integration files
• Create .env.local with placeholders

With Environment Variables

velt add --all --env --api-key="your_velt_api_key" --auth-token="your_velt_auth_token"

This will also populate your environment variables automatically.

Specific Features Only

velt add --presence --cursor

Add only presence and cursor tracking without ReactFlow CRDT.

Force Overwrite

velt add --all --force

Overwrites existing files if you want to update to the latest version.

Handle Dependency Conflicts

velt add --all --legacy-peer-deps

Uses npm's --legacy-peer-deps flag to resolve peer dependency conflicts.

ReactFlow CRDT Only

velt add --reactflow-crdt

Adds collaborative ReactFlow canvas with CRDT synchronization.

Files Generated

The CLI generates the following file structure:

your-project/
├── .env.local                                    # Environment variables
├── app/
│   ├── api/
│   │   └── velt/
│   │       └── token/
│   │           └── route.ts                      # JWT token generation endpoint
│   └── userAuth/
│       ├── AppUserContext.tsx                    # User context provider
│       ├── useAppUser.ts                         # User hook export
│       ├── users.ts                              # Demo users
│       └── LoginPanel.tsx                        # Login UI component
└── components/
    └── velt/
        ├── VeltCollaboration.tsx                 # Main collaboration component
        ├── VeltInitializeUser.tsx                # User authentication hook
        ├── VeltInitializeDocument.tsx            # Document initialization
        ├── VeltTools.tsx                         # Presence, Sidebar, Notifications
        ├── ReactFlowComponent.tsx                # (optional) Collaborative canvas
        ├── hooks/
        │   └── useCurrentDocument.ts             # Document state hook
        └── ui-customization/
            ├── VeltCustomization.tsx             # Wireframe customization wrapper
            ├── VeltComponent1Wf.tsx              # Customization component 1
            ├── VeltComponent2Wf.tsx              # Customization component 2
            └── styles.css                        # Custom styles

Setup After Installation

1. Wrap Your App with VeltProvider

In your app/layout.tsx:

import { VeltProvider } from '@veltdev/react';
import { AppUserProvider } from '@/app/userAuth/useAppUser';
import { useVeltAuthProvider } from '@/components/velt/VeltInitializeUser';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <AppUserProvider>
          <VeltProviderWrapper>
            {children}
          </VeltProviderWrapper>
        </AppUserProvider>
      </body>
    </html>
  );
}

function VeltProviderWrapper({ children }) {
  const { authProvider } = useVeltAuthProvider();
  
  return (
    <VeltProvider apiKey={process.env.NEXT_PUBLIC_VELT_API_KEY!} authProvider={authProvider}>
      {children}
    </VeltProvider>
  );
}

2. Add Collaboration Components

In any page or component:

import { VeltCollaboration } from '@/components/velt/VeltCollaboration';
import VeltTools from '@/components/velt/VeltTools';
import LoginPanel from '@/app/userAuth/LoginPanel';

export default function MyPage() {
  return (
    <>
      <VeltCollaboration />
      <div className="fixed top-4 right-4 flex gap-2">
        <VeltTools />
        <LoginPanel />
      </div>
      {/* Your page content */}
    </>
  );
}

3. (Optional) Add ReactFlow CRDT Canvas

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

export default function CanvasPage() {
  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <ReactFlowComponent />
    </div>
  );
}

4. Set Environment Variables

If you didn't use --env flags during installation, manually add to .env.local:

NEXT_PUBLIC_VELT_API_KEY=your_api_key_here
VELT_AUTH_TOKEN=your_auth_token_here

Get your keys from Velt Dashboard.

5. Run Your App

npm run dev
# or
pnpm dev
# or
yarn dev

Open multiple browser windows to http://localhost:3000 to test real-time collaboration!

Project Analysis

The CLI automatically detects:

• ✅ Package Manager: pnpm, yarn, or npm (based on lockfiles)
• ✅ Router Type: App Router or Pages Router
• ✅ Existing Dependencies: Avoids reinstalling existing packages
• ✅ Tailwind Configuration: Detects if Tailwind is already set up
• ✅ TypeScript Support: Generates TypeScript files by default
• ✅ ReactFlow Version: Ensures compatibility between reactflow v11 and @xyflow/react v12

Dependency Management

The CLI uses smart installation strategies:

1. Standard Install: Tries normal package installation
2. Force Install: Uses --force flag if standard fails
3. Legacy Peer Deps: Falls back to --legacy-peer-deps (npm only)
4. Combined Strategy: Uses both flags as last resort

This ensures successful installation even with complex dependency trees.

ReactFlow CRDT Integration

The CLI includes support for collaborative ReactFlow canvases:

• ✅ Uses @xyflow/react v12+ for best compatibility
• ✅ Integrates @veltdev/reactflow-crdt for real-time synchronization
• ✅ Includes Yjs for CRDT data structures
• ⚠️ Skips CRDT if your project uses reactflow v11 (shows migration guidance)

Troubleshooting

Dependency Conflicts

velt add --all --force
# or
velt add --all --legacy-peer-deps

Existing Files

Use --force to overwrite:

velt add --all --force

Package Manager Issues

The CLI auto-detects your package manager, but you can ensure the correct one by having the appropriate lockfile:

• pnpm-lock.yaml → uses pnpm
• yarn.lock → uses yarn
• package-lock.json → uses npm

Environment Variables Not Working

Make sure you're using the --env flag:

velt add --all --env --api-key="KEY" --auth-token="TOKEN"

Or manually check your .env.local file has both:

• NEXT_PUBLIC_VELT_API_KEY
• VELT_AUTH_TOKEN

Key Features Explained

🔐 Secure Token Generation

The CLI generates a secure backend route (app/api/velt/token/route.ts) that:

• Validates user credentials
• Generates JWT tokens using Velt's v2 API
• Never exposes your auth token to the frontend
• Handles errors gracefully

👥 Demo User System

Includes a complete user authentication system:

• AppUserProvider: React Context for user state
• useAppUser: Hook to access user data
• LoginPanel: Ready-to-use login UI
• Demo users (Michael, Jim, Pam from The Office)
• LocalStorage persistence

🎨 UI Customization

All Velt components are wrapped with:

• VeltWireframe: For deep UI customization
• VeltCustomization: Centralized customization component
• Separate customization files for organization
• CSS file for custom styles

📄 Document Management

Includes document initialization system:

• useCurrentDocument: Hook for current document state
• VeltInitializeDocument: Component that syncs with Velt SDK
• Easy to extend for multi-document apps

Version Compatibility

• Next.js: v13.4.0+ (App Router or Pages Router)
• React: v18.2.0+
• TypeScript: v5.0.0+
• @veltdev/react: v4.5.2-beta.2+
• @xyflow/react: v12.3.0+ (for ReactFlow CRDT)
• Node.js: v16+

Contributing

Contributions are welcome! Please ensure:

• Code matches the existing style
• All features are tested
• Documentation is updated

Support

• 📚 Velt Documentation
• 💬 Discord Community
• 📧 Email Support

Built with ❤️ by the Velt team