Skip to content

README.md

Latest commit

 

History

History
119 lines (84 loc) · 2.39 KB

README.md

File metadata and controls

119 lines (84 loc) · 2.39 KB

Vimux

An interactive learning platform for mastering tmux and Neovim. Practice with real terminals in your browser.

Website: vimux.dev

Features

  • Real neovim and tmux running in isolated containers
  • Interactive lessons from beginner to advanced
  • Keyboard shortcut reference with search
  • Progress tracking across sessions
  • No installation required

Quick Start

git clone https://github.com/devatnull/vimux.git
cd vimux
npm install
npm run dev

Open http://localhost:3000

Architecture

vimux.dev (Vercel)         api.vimux.dev (Hetzner)
    Frontend        --->       Backend
    Next.js                    Node.js + Docker
    Lessons UI                 Real terminals

The frontend runs on Vercel. The backend runs isolated Docker containers with neovim and tmux, connected via WebSocket.

Tech Stack

Frontend

  • Next.js 16 (App Router)
  • TypeScript
  • Tailwind CSS
  • Zustand (state management)
  • xterm.js (terminal emulator)

Backend

  • Node.js
  • Docker (Alpine containers)
  • WebSocket

Project Structure

src/
  app/           Next.js pages
  components/    React components
  lib/           Utilities, types, lessons

backend/
  src/           WebSocket server
  containers/    Docker config, practice files
  deploy/        Server setup scripts

Development

# Frontend
npm run dev

# Backend (requires Docker)
cd backend
npm install
npm run dev

Deployment

See DEPLOY.md for full server setup instructions.

Frontend: Deploy to Vercel, set NEXT_PUBLIC_WS_URL=wss://api.vimux.dev/ws

Backend: See deployment guide for Hetzner/Ubuntu setup.

Contributing

Contributions welcome. Please read the guidelines below.

Adding Lessons

Edit src/lib/lessons.ts. Each lesson needs:

  • Unique ID
  • Title and description
  • Category: tmux, neovim, or workflow
  • Difficulty: beginner, intermediate, or advanced
  • Steps with expected keys and validation

Adding Shortcuts

Edit src/lib/shortcuts.ts. Each shortcut needs:

  • ID, keys array, description
  • Category and optional subcategory

Code Style

  • TypeScript strict mode
  • Functional components with hooks
  • No unnecessary comments in code
  • Run npm run lint before committing

License

MIT

Links