Raxol Packages

Modular architecture for incremental adoption. Choose the packages you need.

Overview

Raxol is designed as a set of focused, independently releasable packages that you can mix and match based on your needs. Start with the minimal core and add features incrementally.

Available Packages

raxol_core

Buffer primitives and terminal rendering core. Zero dependencies, lightweight (< 100KB).

{:raxol_core, "~> 2.0"}

Use when:

• Building CLI tools
• Need minimal footprint
• Want zero dependencies
• Terminal buffer operations only

Includes:

• Buffer operations (create, write, read, clear, resize)
• Box drawing (single, double, rounded, heavy, dashed)
• Style system (colors, bold, italic, underline)
• Renderer (string output, diff rendering)

Does NOT include:

• Phoenix LiveView integration
• Plugin system
• Web rendering
• Enterprise features

raxol_liveview

Phoenix LiveView integration for browser-based terminal rendering.

{:raxol_core, "~> 2.0"},
{:raxol_liveview, "~> 2.0"}

Use when:

• Building web applications
• Want terminal UI in browser
• Need Phoenix LiveView integration
• Require real-time updates

Includes:

• TerminalComponent for LiveView
• Buffer to HTML conversion
• 5 built-in themes (Nord, Dracula, Solarized, Monokai)
• Keyboard and mouse event handling
• CSS styling and theming

Requires:

• raxol_core
• phoenix_live_view (~> 0.20 or ~> 1.0)

raxol_plugin

Plugin system for extensible terminal applications.

{:raxol_core, "~> 2.0"},
{:raxol_plugin, "~> 2.0"}

Use when:

• Building extensible applications
• Need runtime plugin loading
• Want modular architecture
• Third-party integrations

Includes:

• Plugin lifecycle management
• Hot reloading support
• Plugin discovery
• Example plugins (Spotify integration)

Requires:

• raxol_core

raxol (Full Framework)

Complete terminal framework with all features. Coming soon.

{:raxol, "~> 2.0"}  # Coming soon

Use when:

• Want all features
• Building full terminal IDE
• Need enterprise capabilities
• Don't want to manage multiple packages

Includes:

• All of raxol_core
• All of raxol_liveview
• All of raxol_plugin
• Enterprise features (audit logging, encryption, SAML/OIDC)
• Advanced graphics (Sixel support)
• Session continuity
• Real-time collaboration

Package Comparison

Migration Paths

Path 1: Minimal (CLI Tools)

Start with just terminal buffers and rendering.

# mix.exs
def deps do
  [{:raxol_core, "~> 2.0"}]
end

Example:

alias Raxol.Core.{Buffer, Box}

Buffer.create_blank_buffer(80, 24)
|> Box.draw_box(0, 0, 80, 24, :single)
|> Buffer.write_at(10, 5, "Hello, CLI!")
|> Buffer.to_string()
|> IO.puts()

Path 2: Web Integration

Add browser-based terminal rendering to your Phoenix app.

# mix.exs
def deps do
  [
    {:raxol_core, "~> 2.0"},
    {:raxol_liveview, "~> 2.0"}
  ]
end

Example:

defmodule MyAppWeb.TerminalLive do
  use MyAppWeb, :live_view

  def render(assigns) do
    ~H"""
    <.live_component
      module={Raxol.LiveView.TerminalComponent}
      id="terminal"
      buffer={@buffer}
      theme={:nord}
    />
    """
  end
end

See LiveView Integration Cookbook for complete guide.

Path 3: Extensible Architecture

Build plugin-based terminal applications.

# mix.exs
def deps do
  [
    {:raxol_core, "~> 2.0"},
    {:raxol_plugin, "~> 2.0"}
  ]
end

Example:

# Load and use plugins
Raxol.Plugin.Runtime.load_plugin(MyApp.SpotifyPlugin)
Raxol.Plugin.Runtime.execute_command("spotify:play")

See Plugin Development Guide for details.

Path 4: Full Framework

Get everything in one package (coming soon).

# mix.exs
def deps do
  [{:raxol, "~> 2.0"}]  # Coming soon
end

Includes all features from all packages plus enterprise capabilities.

Installation Guide

Step 1: Choose Your Packages

Based on your needs:

• CLI tool? → raxol_core only
• Web terminal? → raxol_core + raxol_liveview
• Extensible app? → raxol_core + raxol_plugin
• Everything? → raxol (when available)

Step 2: Add to mix.exs

# mix.exs
def deps do
  [
    # Choose your packages
    {:raxol_core, "~> 2.0"},
    {:raxol_liveview, "~> 2.0"},  # Optional
    {:raxol_plugin, "~> 2.0"}     # Optional
  ]
end

Step 3: Fetch Dependencies

mix deps.get

Step 4: Start Building

See respective documentation for each package:

• Quickstart Guide - Get started quickly
• Core Concepts - Understand the architecture
• Migration Guide - Migrate existing code

Upgrading Between Packages

Adding LiveView Support

Already using raxol_core and want to add web rendering?

# Before
{:raxol_core, "~> 2.0"}

# After
{:raxol_core, "~> 2.0"},
{:raxol_liveview, "~> 2.0"}

No code changes needed to existing buffer logic. Just add LiveView component.

Adding Plugin Support

# Before
{:raxol_core, "~> 2.0"}

# After
{:raxol_core, "~> 2.0"},
{:raxol_plugin, "~> 2.0"}

Existing code continues to work. Add plugins incrementally.

Upgrading to Full Framework

# Before
{:raxol_core, "~> 2.0"},
{:raxol_liveview, "~> 2.0"},
{:raxol_plugin, "~> 2.0"}

# After
{:raxol, "~> 2.0"}  # Coming soon

All packages included, no API changes.

Performance Considerations

Package Overhead

Measured on M1 Mac, cold start

Optimization Tips

1. Use raxol_core only if you don't need web/plugins (fastest)
2. Lazy load plugins to reduce initial startup time
3. Configure runtime: false for testing/docs (reduces deps)
4. Tree shaking - Only import what you use

Package Development Status

Current Status (October 2025)

Publishing Timeline

All packages are ready for Hex.pm publication:

• raxol_core: Independent, zero deps
• raxol_liveview: Depends on raxol_core
• raxol_plugin: Depends on raxol_core

Next Steps:

1. Final review of package.exs files
2. Verify hex.pm metadata
3. Coordinate release versions
4. Publish to Hex.pm

Getting Help

Package-Specific Questions

• raxol_core: Buffer API Reference
• raxol_liveview: LiveView Integration
• raxol_plugin: Plugin Development

General Support

• GitHub Issues - Bug reports and features
• Documentation - Complete documentation index
• Examples - Working code examples

Frequently Asked Questions

Do I need all packages?

No! Start with raxol_core and add packages as needed. They're designed for incremental adoption.

Can I switch packages later?

Yes. All packages share the same core API. You can add or remove packages without rewriting code.

What's the difference between raxol_liveview and raxol_web?

raxol_liveview is the new name (v2.0+). raxol_web was the v1.x name. They're the same functionality, just renamed for clarity.

Which package should I start with?

• Building a CLI? → raxol_core
• Building a web app? → raxol_core + raxol_liveview
• Need plugins? → raxol_core + raxol_plugin
• Want everything? → Wait for raxol (full) or use all packages

Are there version compatibility issues?

No. All packages use the same version numbering and are tested together. raxol_core 2.0 works with raxol_liveview 2.0 and raxol_plugin 2.0.

Can I use runtime: false?

Yes! Use {:raxol_core, "~> 2.0", runtime: false} for:

• Documentation generation
• Testing helpers
• UI components without terminal emulator

See README for details.

Additional Resources

• Quickstart Guide - 5/10/15 minute tutorials
• Core Concepts - Understand buffers and rendering
• Migration Guide - Migrate from custom code
• API Reference - Complete API documentation
• Cookbook - Practical recipes and patterns

Ready to get started? Choose your package(s) above and follow the Quickstart Guide.