Raxol

Terminal Application Framework

Terminal framework supporting React, Svelte, LiveView, and HEEx UI patterns.

Features

• Sub-microsecond parser operations
• Multi-framework UI support (React, Svelte, LiveView, HEEx)
• Enterprise features: audit logging, encryption, SAML/OIDC
• Graphics: Sixel support, session continuity
• NEW: VIM navigation, command parser, fuzzy search, virtual filesystem, cursor effects

Modular Packages (v2.0+)

Raxol is now available as focused, independently releasable packages:

• raxol_core - Lightweight buffer primitives (< 100KB, zero deps)
• raxol_liveview - Phoenix LiveView integration
• raxol_plugin - Plugin system
• raxol - Full framework (includes all packages)

See Package Guide for detailed comparison, migration paths, and installation instructions.

Quick Start

Installation

Choose your package based on needs:

# Minimal - Just terminal buffers
{:raxol_core, "~> 2.0"}

# Web integration - Add LiveView support
{:raxol_core, "~> 2.0"},
{:raxol_liveview, "~> 2.0"}

# Extensible apps - Add plugin system
{:raxol_core, "~> 2.0"},
{:raxol_plugin, "~> 2.0"}

# Or use v1.x (full framework)
{:raxol, "~> 2.0"}

Using runtime: false provides UI components without terminal emulator runtime for:

• Web applications
• Component libraries
• Testing UI logic
• Reduced application size

Development Setup

# Clone and explore
git clone https://github.com/Hydepwns/raxol.git
cd raxol
mix deps.get

# Run quality checks
mix raxol.check

# Run tests
TMPDIR=/tmp SKIP_TERMBOX2_TESTS=true MIX_ENV=test mix test

# Generate type specs
mix raxol.gen.specs lib --recursive

Choose Your Framework

use Raxol.UI, framework: :react      # Familiar React patterns
use Raxol.UI, framework: :svelte     # Reactive with compile-time optimization
use Raxol.UI, framework: :liveview   # Phoenix LiveView patterns
use Raxol.UI, framework: :heex       # Phoenix templates
use Raxol.UI, framework: :raw        # Direct terminal control

React-Style Example

defmodule MyApp do
  use Raxol.Component

  def render(assigns) do
    ~H"""
    <Box padding={2}>
      <Text color="green" bold>Hello, Raxol!</Text>
      <Button on_click={@on_click}>Click me!</Button>
    </Box>
    """
  end
end

Emulator Usage

# Default configuration
emulator = Emulator.new(80, 24)

# With GenServers for concurrent operations
emulator = Emulator.new(80, 24, use_genservers: true)

# Minimal configuration
emulator = Emulator.new(80, 24, enable_history: false, alternate_buffer: false)

View more examples →

Components-Only Mode

When importing Raxol with runtime: false, you get access to:

UI Components

• All framework adapters (React, Svelte, LiveView, HEEx)
• Complete component library (Button, Input, Table, Modal, etc.)
• State management and context systems
• Animation and transition engines
• Theme system and styling utilities

Not Included in Components-Only

• Terminal emulator runtime
• ANSI/VT100 sequence processing
• PTY/TTY management
• SSH session handling
• Sixel graphics rendering

This makes Raxol perfect as a lightweight UI component library for web applications or other non-terminal use cases.

Architecture

Terminal Framework

• VT100/ANSI compliance with modern extensions
• Sixel graphics, GPU acceleration
• Mouse support, event handling
• Tab completion, command history

UI System

• Universal features: actions, transitions, context, slots
• 60 FPS animation engine
• Component composition, theming

Enterprise Features

• Session continuity
• Real-time collaboration with CRDT sync
• SOC2/HIPAA/GDPR audit logging
• AES-256-GCM encryption with key rotation

Performance

Additional Metrics

• Cursor Operations: 0.5μs per movement
• Buffer Write: 1.2μs per character
• Screen Clear: <50μs for full screen
• Input Latency: <2ms keyboard to screen
• Render Performance: 60 FPS maintained

Documentation

Getting Started

• Quickstart - 5/10/15 minute tutorials
• Core Concepts - Understand buffers and rendering
• Migration Guide - For teams with existing terminal code

Cookbooks

• LiveView Integration - Render terminals in Phoenix
• Performance Optimization - 60fps techniques
• Theming - Custom color schemes

Features

• VIM Navigation - VIM-style keybindings and movement
• Command Parser - Tab completion, history, argument parsing
• Fuzzy Search - Multi-mode search with highlighting
• File System - Virtual filesystem with Unix commands
• Cursor Effects - Visual trails and glow effects
• Features Overview - Complete guide to all features

API Reference

• Buffer API - Complete buffer operations reference
• Architecture - Design decisions and internals
• Full Documentation - Complete API reference

Recent Features

• Feature Additions (v2.0.0 Phase 6) - VIM navigation, command parser, fuzzy search, filesystem, cursor effects
• Documentation Overhaul (v2.0.0 Phase 4) - Beginner-friendly guides and practical cookbooks
• Plugin System (v2.0.0 Phase 3) - Spotify plugin showcase
• LiveView Integration (v2.0.0 Phase 2) - Terminal rendering in Phoenix
• Raxol.Core (v2.0.0 Phase 1) - Lightweight buffer primitives (< 100KB, zero deps)
• Code Consolidation (v1.5.4) - BaseManager pattern, TimerManager integration, 99.8% test coverage
• Type Spec Generator (v1.4.1) - Automated type specification generation
• Unified Configuration (v1.4.1) - TOML-based configuration system

VS Code Extension

Development version available in editors/vscode/. To install:

cd editors/vscode
npm install
npm run compile
code --install-extension .

Features: syntax highlighting, IntelliSense, component snippets, live preview

Use Cases

Use cases: terminal IDEs, DevOps tools, system monitoring, database clients, chat applications, games.

License

MIT License - see LICENSE.md