Termix

A React-like framework for building interactive terminal user interfaces (TUIs) with TypeScript. Termix provides a component-based architecture with hooks, making it easy to create dynamic and responsive terminal applications.

Features

✨ Component-Based - Build UIs with reusable functional components
⚡ React-Like API - Familiar useState and hooks patterns
⌨️ Keyboard Support - Built-in keyboard input handling
🎨 Styling - Inline styles and CSS classes for terminal colors and formatting
📐 Layout Engine - Yoga layout for flexible and responsive UIs
🚀 Fast Rendering - Efficient diff-based rendering with minimal screen updates

Quick Start

Installation

To scaffold a new project, use the create CLI:

npx create-nxt-terminal my-tui-app
# or
bunx create-nxt-terminal my-tui-app

Hello World

Projects created with the CLI use file-based routing. Your main entry point is screens/home.tsx:

import { Termix } from 'nxt-terminal';
import { Sheet, Text } from 'nxt-terminal/components';

export default function Home() {
  return (
    <Sheet>
      <Text color="#00ff00" bold>
        Hello, Termix!
      </Text>
    </Sheet>
  );
}

Run the development server with hot-reloading:

npm run dev
# or
bun run dev

Core Concepts

Components

Components are TypeScript functions that return JSX elements:

import { useState, useKeyboard } from 'nxt-terminal';
import { Box, Text } from 'nxt-terminal/components';

function Counter() {
  const [count, setCount] = useState(0);

  useKeyboard((key) => {
    if (key.name === 'up') setCount(count + 1);
    if (key.name === 'down') setCount(count - 1);
  });

  return (
    <Box style={{ padding: 1 }}>
      <Text>Count: {count}</Text>
    </Box>
  );
}

State Management

Use useState hook to manage component state (just like React):

const [value, setValue] = useState(initialValue);

Keyboard Input

Handle keyboard events with useKeyboard:

useKeyboard((key) => {
  if (key.name === 'enter') {
    handleSubmit();
  }
  if (key.ctrl && key.name === 'c') {
    process.exit(0);
  }
});

Styling

Style components with inline styles or CSS classes:

// Inline styles
<Text style={{ fg: '#ff0000', bold: true }}>Red Bold Text</Text>

// CSS classes
<Text className="text-blue-500 font-bold">Blue Text</Text>

Built-in Components

• <Sheet> - Full-screen container (100% width/height)
• <Box> - Flexible layout container with flexbox support
• <Text> - Text rendering with color and formatting
• <Input> - Interactive text input field

See Components Guide for detailed documentation.

Examples

The project includes several ready-to-run examples:

1. Counter App - Simple state management
2. Todo List - Managing arrays and lists
3. Menu Navigation - Arrow key navigation
4. Login Form - Multiple inputs and validation
5. Dashboard - Complex layouts with real-time updates

Documentation

• Getting Started - Introduction and basic usage
• API Reference - Complete API documentation
• Advanced Patterns - Complex component patterns and best practices

Development

Build

bun run build

Watch Mode

bun run dev

Build CLI

bun run build:cli

Project Structure

src/
├── components/          # Built-in components (Box, Text, Sheet, Input)
├── hooks/              # React-like hooks (useState, useKeyboard)
├── layout/             # Layout engine (Yoga integration)
├── renderer/           # Rendering and diffing logic
├── input/              # Keyboard input handling
├── styles/             # Style system and class resolution
├── createElement.ts    # VNode creation
├── reconciler.ts       # Component tree resolution and rendering
├── terminal.ts         # Terminal mode setup/cleanup
└── index.ts           # Main entry point

docs/
├── GETTING_STARTED.md   # Beginner's guide
├── API.md              # Full API reference
└── PATTERNS.md         # Advanced patterns

examples/
├── 01-counter.tsx      # Simple counter
├── 02-todo-list.tsx    # Todo management
├── 03-menu.tsx         # Menu navigation
├── 04-login-form.tsx   # Form handling
└── 05-dashboard.tsx    # Complex dashboard

Key Technologies

• TypeScript - Type-safe development
• Yoga Layout - Flexbox-based layout engine
• Node.js - Built for Bun and Node.js terminals
• React-inspired API - Familiar component and hooks patterns

Use Cases

Termix is perfect for:

• 📊 System monitoring dashboards
• 🎮 Terminal games and interactive demos
• 📝 CLI tools with interactive UIs
• 🔧 Configuration utilities
• 📋 Task management applications
• 🎯 Any interactive terminal application

API Overview

Functions

// Render a component tree to terminal
render(root: VNode): void

// Create a virtual node
createElement(type: string | Function, props, ...children): VNode

Hooks

// State management
const [state, setState] = useState<T>(initialValue: T): [T, (T) => void]

// Keyboard input
useKeyboard((key: Key) => void): void

Style Properties

Common style properties include:

• fg - Foreground color (hex: "#ffffff")
• bg - Background color
• bold, italic, underline - Text formatting
• padding, gap - Spacing
• flexDirection - "row" or "column"
• width, height - Dimensions
• border, borderColor - Borders

See API Reference for complete list.

Keyboard Keys

Common key names in useKeyboard:

• 'enter', 'tab', 'escape', 'space'
• 'up', 'down', 'left', 'right'
• 'backspace', 'delete'
• Single characters: 'a', '1', '@', etc.

Modifiers: key.ctrl, key.meta, key.shift

Tips & Best Practices

1. Keep components small - Break large UIs into smaller focused components
2. Use state locally - Keep state as close to usage as possible
3. Handle exit gracefully - Provide keyboard shortcuts to exit
4. Test in terminal - Different terminals may render slightly differently
5. Use colors wisely - High contrast improves readability

Limitations

• Designed for modern terminals with ANSI color support
• Some complex Unicode characters may not render correctly
• Terminal size affects layout calculations
• No mouse support (keyboard-only)

License

MIT

Support

For issues, questions, or contributions:

• Check the examples directory
• Read the documentation
• Review existing issues on GitHub

Next Steps

• 🚀 Try the Getting Started guide
• 👀 Explore the examples
• 📚 Read the API documentation
• 🎨 Learn advanced patterns

Happy coding! 🎉