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

$3

``bash
npx @veltdev/add-velt add --all
`

$3

`bash
cd add-velt-next-js
npm link
`

Quick Start

Navigate to your existing Next.js project and run:

`bash


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

$3

`bash
velt add [options]
`

$3

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

$3

`bash
velt add --all
`

This will:
- Analyze your project structure
- Install all required dependencies
- Generate all Velt integration files
- Create .env.local with placeholders

$3

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

This will also populate your environment variables automatically.

$3

`bash
velt add --presence --cursor
`

Add only presence and cursor tracking without ReactFlow CRDT.

$3

`bash
velt add --all --force
`

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

$3

`bash
velt add --all --legacy-peer-deps
`

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

$3

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

$3

In your app/layout.tsx:

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

export default function RootLayout({ children }) {
return (




{children}




);
}

function VeltProviderWrapper({ children }) {
const { authProvider } = useVeltAuthProvider();

return (

{children}

);
}
`

$3

In any page or component:

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

export default function MyPage() {
return (
<>




{/ Your page content /}

);
}
`

$3

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

export default function CanvasPage() {
return (



);
}
`

$3

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

`bash
NEXT_PUBLIC_VELT_API_KEY=your_api_key_here
VELT_AUTH_TOKEN=your_auth_token_here
`

Get your keys from Velt Dashboard.

$3

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

$3

`bash
velt add --all --force


or


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

$3

Use --force to overwrite:

`bash
velt add --all --force
`

$3

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

$3

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

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

$3

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

$3

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

$3

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

$3

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