TipTap Rails Collaborative Editor

A real-time collaborative document editor built with Ruby on Rails, TipTap 3.x, and Hocuspocus. Features live multi-user editing, comments with @mentions, version history, and Markdown support.

🚀 Features

• Real-time Collaboration: Multiple users can edit documents simultaneously with live cursor tracking
• Rich Text Editing: Full formatting support with TipTap 3.x - bold, italic, headings, lists, links, code blocks
• Comments System:
  • Add comments to selected text
  • @mention users in comments
  • Resolve, reopen, and delete comments
  • Toggle comments panel visibility
• Markdown Support:
  • Paste Markdown that auto-formats in the editor
  • Export content as Markdown
  • Full syntax highlighting for code blocks
• Version History: Track and restore document changes
• AI Text Improvements: Enhance, simplify, fix grammar, and more (mock implementation, ready for AI integration)
• Modern UI: Clean interface with Tailwind CSS, bubble menus, and floating toolbars

🛠️ Tech Stack

Backend

• Ruby on Rails 7.x (API mode)
• PostgreSQL - Database for documents, users, and comments
• Action Cable - WebSocket support
• RESTful API - Clean API design

Frontend

• React 18 with Vite
• TipTap 3.x - Headless rich text editor
• Yjs - CRDT for conflict-free collaboration
• Hocuspocus Provider - WebSocket collaboration client
• Tailwind CSS - Utility-first styling
• tiptap-markdown - Markdown support

Collaboration Server

• Hocuspocus - WebSocket server for real-time sync
• Node.js - Server runtime
• Yjs - Document synchronization

📋 Prerequisites

Option 1: Docker (Recommended)

• Docker and Docker Compose installed
• That's it! 🎉

Option 2: Local Development

• Ruby 3.x
• Rails 7.x
• Node.js 18.x or higher
• PostgreSQL 14.x or higher

🚀 Quick Start with Docker (Recommended)

1. Clone and Start

# Clone the repository
git clone https://github.com/yourusername/tiptap-rails-collab.git
cd tiptap-rails-collab

# Start all services with Docker Compose
docker compose up --build

# That's it! 🚀

2. Access the Application

After containers are running:

• Frontend: http://localhost:3002
• Rails API: http://localhost:3000
• Hocuspocus WebSocket: ws://localhost:1234
• PostgreSQL: localhost:5432
• Redis: localhost:6379

3. Initialize Database (First Time Only)

# In a new terminal, run migrations and seed data
docker-compose exec rails rails db:create
docker-compose exec rails rails db:migrate
docker-compose exec rails rails db:seed

🚀 Alternative: Manual Setup (Without Docker)

Click to expand manual setup instructions

1. Clone the Repository

git clone https://github.com/yourusername/tiptap-rails-collab.git
cd tiptap-rails-collab

2. Backend Setup

# Install Ruby dependencies
bundle install

# Setup database
rails db:create
rails db:migrate
rails db:seed  # Creates 25 test users and sample documents

# Start Rails server
rails server
# API runs on http://localhost:3000

3. Collaboration Server Setup

cd hocuspocus-server

# Install dependencies
npm install

# Start the collaboration server
npm start
# WebSocket server runs on ws://localhost:1234

4. Frontend Setup

cd frontend

# Install dependencies
npm install

# Start development server
npm run start
# Frontend runs on http://localhost:3002 (or 3003 if port is taken)

🐳 Docker Services

The docker-compose.yml file includes:

Service	Port	Description
rails	3000	Rails API backend
frontend	3002	React application
hocuspocus	1234	WebSocket collaboration server
postgres	5432	PostgreSQL database
redis	6379	Redis cache (for ActionCable)

📁 Project Structure

tiptap-rails-collab/
├── app/                          # Rails backend
│   ├── controllers/
│   │   └── api/v1/
│   │       ├── documents_controller.rb   # Document CRUD
│   │       ├── comments_controller.rb    # Comment management
│   │       └── users_controller.rb       # User search for @mentions
│   └── models/
│       ├── document.rb          # Document model
│       ├── comment.rb           # Comment model
│       └── user.rb              # User model
├── frontend/                    # React frontend
│   ├── src/
│   │   ├── components/
│   │   │   ├── CollabEditor-v3.jsx      # Main editor (TipTap 3.x)
│   │   │   ├── DocumentList.jsx         # Document sidebar
│   │   │   └── ChangeHistory.jsx        # Version history
│   │   └── services/
│   │       ├── documentService.js       # Document API
│   │       ├── commentService.js        # Comment API
│   │       └── aiService.js            # AI text improvements
│   ├── package.json
│   └── vite.config.js
├── hocuspocus-server/           # Collaboration server
│   ├── server.js               # WebSocket server setup
│   └── package.json
├── db/
│   ├── migrate/                # Database migrations
│   └── seeds.rb                # Sample data
├── docker-compose.yml          # Docker services orchestration
├── Dockerfile.rails            # Rails container definition
└── config/
    └── routes.rb               # API routes

🔌 API Endpoints

Documents

GET    /api/v1/documents           # List all documents
GET    /api/v1/documents/:id       # Get single document
POST   /api/v1/documents           # Create document
PATCH  /api/v1/documents/:id       # Update document
DELETE /api/v1/documents/:id       # Delete document

Comments

GET    /api/v1/documents/:document_id/comments       # List comments
POST   /api/v1/documents/:document_id/comments       # Create comment
PATCH  /api/v1/documents/:doc_id/comments/:id       # Update (resolve/reopen)
DELETE /api/v1/documents/:doc_id/comments/:id       # Delete comment

Users

GET    /api/v1/users               # List all users
GET    /api/v1/users/search?q=     # Search users for @mentions

💻 Usage Guide

Basic Editing

1. Select a document from the sidebar or create a new one
2. Use the toolbar for formatting (Bold, Italic, Headings, Lists)
3. Select text to see the bubble menu with quick formatting options

Collaboration

1. Open the same document in multiple browser tabs/windows
2. You'll see live cursors of other users
3. Changes sync instantly across all clients
4. User names appear on their cursors

Comments

1. Select any text in the editor
2. Click "Add Comment" in the bubble menu
3. Type your comment (use @ to mention users)
4. Comments appear in the right panel
5. Toggle panel visibility with the "Comments" button
6. Resolve, reopen, or delete comments as needed

Markdown

1. Paste Markdown: Copy any Markdown text and paste - it auto-formats
2. Test Markdown: Click "Test Markdown" button to see sample formatting
3. Export: Click "Get as Markdown" to export current content

Version History

1. Click "Show History" to see document versions
2. View changes with timestamps
3. Restore previous versions if needed

🧪 Development

Docker Development Commands

# View logs for all services
docker-compose logs -f

# View logs for specific service
docker-compose logs -f rails
docker-compose logs -f frontend

# Access Rails console
docker-compose exec rails rails console

# Run Rails migrations
docker-compose exec rails rails db:migrate

# Access bash shell in container
docker-compose exec rails bash
docker-compose exec frontend sh

# Rebuild specific service
docker-compose build rails
docker-compose build frontend

# Stop all services
docker-compose down

# Stop and remove volumes (full reset)
docker-compose down -v

Running Tests with Docker

# Rails tests
docker-compose exec rails rails test

# Frontend tests
docker-compose exec frontend npm test

Running Tests without Docker

# Rails tests
rails test

# Frontend tests
cd frontend && npm test

Building for Production

# With Docker
docker-compose -f docker-compose.production.yml build
docker-compose -f docker-compose.production.yml up

# Without Docker
RAILS_ENV=production rails assets:precompile
RAILS_ENV=production rails db:migrate
cd frontend && npm run build

Adding Features

1. New API endpoint: Add controller in app/controllers/api/v1/
2. New editor feature: Modify frontend/src/components/CollabEditor-v3.jsx
3. New TipTap extension: Add to extensions array in editor setup
4. Collaboration logic: Update hocuspocus-server/server.js
5. After changes: Rebuild containers with docker-compose build

🐛 Troubleshooting

Docker Issues

1. Container won't start

# Check logs
docker-compose logs rails
docker-compose logs frontend

# Rebuild from scratch
docker-compose down -v
docker-compose build --no-cache
docker-compose up

2. Port conflicts with Docker

# Check what's using the port
lsof -i :3000
lsof -i :3002
lsof -i :1234

# Change ports in docker-compose.yml if needed

3. Database connection errors in Docker

# Ensure postgres is running
docker-compose ps postgres

# Reset database
docker-compose exec rails rails db:drop
docker-compose exec rails rails db:create
docker-compose exec rails rails db:migrate
docker-compose exec rails rails db:seed

Non-Docker Issues

1. Vite "Outdated Optimize Dep" errors

cd frontend
rm -rf node_modules/.vite
npm run start

2. Port already in use (local dev)

# Kill process on port 3000
lsof -ti:3000 | xargs kill -9

# Frontend auto-tries ports 3002, 3003

3. WebSocket connection failed

• Check Hocuspocus server is running on port 1234
• Verify no firewall blocking WebSocket connections
• Check browser console for specific errors
• With Docker: ensure all containers are running

4. Database connection issues (local)

# Reset database
rails db:drop
rails db:create
rails db:migrate
rails db:seed

5. Missing @mention users

# With Docker
docker-compose exec rails rails db:seed

# Without Docker
rails db:seed

Debug Tips

• Check browser console for JavaScript errors
• Check Rails logs for API errors: tail -f log/development.log
• Check Hocuspocus logs in the terminal running the server
• Verify services are running on correct ports

🔧 Configuration

Environment Variables

Create .env files:

Backend (.env)

DATABASE_URL=postgresql://localhost/tiptap_collab_dev
RAILS_ENV=development
SECRET_KEY_BASE=your-secret-key

Frontend (frontend/.env)

VITE_API_URL=http://localhost:3000
VITE_WS_URL=ws://localhost:1234

Customization

• Styling: Modify Tailwind classes in components
• Editor toolbar: Edit toolbar buttons in CollabEditor-v3.jsx
• TipTap extensions: Add/remove in extensions array
• AI features: Implement real AI in aiService.js

📝 Key Implementation Details

TipTap 3.x Migration

• Uses CollaborationCaret instead of CollaborationCursor
• Imports from @tiptap/extensions for consolidated extensions
• Named imports for Color, TextStyle, FontFamily

Collaboration Architecture

• Yjs documents for CRDT-based sync
• Hocuspocus provider manages WebSocket connection
• Each document has unique collaboration session
• Conflict-free merging of concurrent edits

Comments System

• Comments linked to text positions
• Preserved through collaborative edits
• Rich text support with @mentions
• Separate active/resolved states

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit changes (git commit -m 'Add some AmazingFeature')
4. Push to branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• TipTap - Incredible headless editor framework
• Hocuspocus - Plug & play collaboration backend
• Yjs - CRDT framework powering real-time sync
• Rails - The web framework that doesn't hurt
• Tailwind CSS - For rapid UI development

📧 Support

For issues, questions, or suggestions:

• Open an issue on GitHub
• Check existing issues for solutions
• Include browser console logs and error messages when reporting bugs