🌐 CloudGrid

A high-performance, infinite canvas library for React with WebAssembly-powered rendering

Build infinite canvas applications with 2000+ media items at 60 FPS. Powered by WebAssembly, Web Workers, and React.

🚀 Quick Start

npm install @convadraw/cloudgrid

import { CloudGrid } from '@convadraw/cloudgrid';
import '@convadraw/cloudgrid/cloudgrid.css';

function App() {
  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <CloudGrid />
    </div>
  );
}

📖 Full Documentation • 🎮 Live Demo • 📦 NPM Package

✨ Features

Feature	Description
🚀 High Performance	WebAssembly-powered canvas operations with spatial indexing
🎨 2000+ Items	Handle thousands of media items smoothly at 60 FPS
🔄 Undo/Redo	Full history management with batch operations
🎯 Smart Selection	Multi-select with rubber band, group move/resize
📐 Grid Snapping	Configurable grid with dynamic visual feedback
🔍 Smooth Zoom	Animated camera controls with easing functions
🎭 LOD System	Level-of-detail rendering for optimal memory usage
🧵 Web Workers	Non-blocking grid rendering and image processing
🎨 Color Sorting	Sort media by dominant RGB colors
📦 TypeScript	Full type safety and IntelliSense support

📊 Performance

✅ 2000+ media items at 60 FPS
✅ <400MB memory usage with high-res images
✅ Smooth animations with hardware acceleration
✅ Non-blocking operations via Web Workers
✅ Instant undo/redo for all operations

🏗️ Architecture

CloudGrid is built as a monorepo with multiple packages:

cloudgrid/
├── packages/
│   ├── cloudgrid/       # Main React SDK
│   ├── wasm/            # WebAssembly module (AssemblyScript)
│   ├── editor/          # Core editor logic
│   ├── state/           # State management
│   └── primitives/      # Math utilities
└── apps/
    └── www/             # Demo application

Technology Stack

• React 18 - UI framework with concurrent features
• Konva.js - High-performance canvas rendering
• AssemblyScript - WebAssembly compilation for critical operations
• Web Workers - Background processing for grid rendering & image loading
• Tailwind CSS v4 - Modern utility-first styling
• TypeScript - End-to-end type safety
• Turborepo - Fast, scalable monorepo build system

📦 Packages

@convadraw/cloudgrid

The main React SDK. This is what you install and use in your applications.

npm install @convadraw/cloudgrid

@cloudgrid/wasm

WebAssembly module for high-performance canvas operations:

• Spatial indexing (Quadtree)
• Viewport culling
• Grid snapping
• Command history (undo/redo)
• Batch operations

@cloudgrid/editor

Framework-agnostic editor logic.

@cloudgrid/state

Centralized state management.

@cloudgrid/primitives

Math utilities (vectors, boxes, snapping).

🎯 Use Cases

• Design Tools: Build Figma-like design applications
• Image Galleries: Infinite scrolling image galleries
• Mood Boards: Create visual mood boards with 1000s of images
• Photo Editors: Build photo organization and editing tools
• Data Visualization: Visualize large datasets on infinite canvas
• Whiteboarding: Real-time collaborative whiteboarding apps

🚦 Getting Started

1. Installation

npm install @convadraw/cloudgrid

2. Import CSS

import '@convadraw/cloudgrid/cloudgrid.css';

3. Use Component

import { CloudGrid } from '@convadraw/cloudgrid';

function App() {
  return <CloudGrid />;
}

4. Add Controls

import { CloudGrid, useCamera, selectItems, zoomToSelected } from '@convadraw/cloudgrid';

function App() {
  const camera = useCamera();

  return (
    <>
      <button onClick={() => camera.resetView()}>Reset</button>
      <CloudGrid />
    </>
  );
}

See full documentation →

🎮 Demo

Try the live demo: https://yourusername.github.io/cloudgrid

Or run locally:

git clone https://github.com/yourusername/cloudgrid.git
cd cloudgrid
npm install
npm run dev

Open http://localhost:3000

🧪 Development

This is a Turborepo monorepo. To get started:

Prerequisites

• Node.js 18+
• npm 9+

Setup

# Clone the repository
git clone https://github.com/yourusername/cloudgrid.git
cd cloudgrid

# Install dependencies
npm install

# Build all packages
npm run build

# Run demo app
cd apps/www
npm run dev

Commands

npm run build        # Build all packages
npm run dev          # Start demo app
npm run lint         # Lint all packages
npm run test         # Run tests (when available)
npm run clean        # Clean build artifacts

Package Development

To develop a specific package:

# Build WASM module
cd packages/wasm
npm run build

# Build React SDK
cd packages/cloudgrid
npm run build

# Watch mode (auto-rebuild)
npm run build -- --watch

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

Development Workflow

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

Code Style

• Use TypeScript for all new code
• Follow existing code style (ESLint)
• Add tests for new features
• Update documentation

📄 License

MIT © 2026 - see LICENSE for details

🙏 Acknowledgments

• Inspired by tldraw - Excellent infinite canvas library
• Built with Konva.js - HTML5 2D canvas library
• Icons by Phosphor Icons - Beautiful icon family
• Styled with Tailwind CSS - Utility-first CSS framework

📞 Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions
• 📧 Email

🗺️ Roadmap

• React Native support
• Video support
• Text editing
• Real-time collaboration
• Export to PNG/SVG
• Layers & groups
• Custom shapes
• Pen tool
• Animation timeline

⭐ Star History

If you find CloudGrid useful, please consider giving it a star! ⭐

---

Made with ❤️ by the CloudGrid team