Raxol

A terminal application toolkit for Elixir, providing components and a runtime for building interactive TUI applications.

Note: Pre-release software. APIs may change before v1.0.

Features

ANSI Terminal Emulation: Robust handling of ANSI escape codes, colors, and Unicode characters.
Component Model: Build UIs with reusable components inspired by web frameworks.
Layout System: Flexible layouts for arranging components within the terminal window.
Performance: Optimized rendering pipeline with double buffering and efficient updates.

Installation

Add raxol to your list of dependencies in mix.exs:

def deps do
  [
    {:raxol, "~> 0.1.0"} # Or use {:raxol, github: "Hydepwns/raxol"} for development
  ]
end

Then, fetch the dependencies:

mix deps.get

For detailed installation options and requirements, see the Installation Guide.

Getting Started

Here's a basic example of a Raxol application:

defmodule MyApp do
  use Raxol.App

  @impl true
  def render(assigns) do
    ~H"""
    <box border="single">
      <text>Hello, Raxol!</text>
    </box>
    """
  end
end

# Start the application
{:ok, _pid} = Raxol.Runtime.start_link(app: MyApp)

# Keep the application running (e.g., in an IEx session or supervisor)

Note: Use Raxol.App for the main application entry point and Raxol.View for reusable UI components. Raxol also supports nested component functions (e.g., box do ... end). See the examples in /examples and the Getting Started Tutorial for more details on both approaches.

For a more comprehensive guide, please refer to the Getting Started Tutorial.

Explore the /examples directory for more detailed usage patterns and advanced features.

Documentation

Detailed documentation can be found in the /docs directory or online (TODO: Add the hosted documentation link here):

Development

To set up your development environment, please see the Development Environment Setup guide.

Common development commands:

# Run the full test suite
mix test

# Run static analysis (Credo for style, Dialyzer for types)
mix credo
mix dialyzer

# Format code
mix format

We also provide a range of helper scripts for various development tasks, including:

Running different test suites (integration, platform-specific, visualization, etc.)
Performing code quality and pre-commit checks
Managing database setup and diagnostics
Building releases
Simulating CI/CD workflows locally

For detailed information on all available scripts and their usage, please refer to the Scripts Documentation.

GitHub Actions

See GitHub Actions README for detailed instructions...

Project Structure

/assets - Static assets (e.g., images, fonts)
/docker - Docker configurations (e.g., for local testing with act)
/docs - User documentation
/examples - Example applications and code samples
/extensions - IDE integrations and extensions (e.g., VS Code)
/frontend - Frontend JavaScript/TypeScript configurations and assets
/lib - Core Elixir code
/pages - In-depth documentation/articles (e.g., for site generation)
/priv - Non-source code assets (e.g., templates, static files for releases)
/scripts - Helper scripts for development tasks
/themes - Theme definitions for styling

Contributing

Contributions are welcome! Please see the CONTRIBUTING.md file for guidelines.

License

MIT License - see LICENSE file for details.