Opentui Projects

OpenTUI Projects

Expert assistance for scaffolding OpenTUI projects and exploring examples.

Quick Start (create-tui)

The fastest way to create an OpenTUI project:

# Using create-tui (recommended)
bun create tui my-app

# Or with npm
npm create tui my-app

Template Selection

# Choose from available templates:
# - minimal: Minimal setup
# - basic-cli: Basic CLI tool
# - dashboard: Dashboard layout
# - form-app: Form-based application
# - editor: Text editor template
# - game: Simple game template

bun create tui my-app --template dashboard

Manual Project Setup

Core Project Structure

my-opentui-app/
├── package.json
├── tsconfig.json
├── src/
│   ├── main.tsx
│   ├── components/
│   └── utils/
└── README.md

package.json

{
  "name": "my-opentui-app",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "dev": "bun run src/main.tsx",
    "build": "tsc",
    "start": "bun run dist/main.js"
  },
  "dependencies": {
    "@opentui/core": "latest",
    "@opentui/react": "latest",
    "react": "^18.3.0"
  },
  "devDependencies": {
    "@types/node": "^20.0.0",
    "typescript": "^5.3.0"
  }
}

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "types": ["node"]
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

Basic Entry Point

// src/main.tsx
import { createCliRenderer } from "@opentui/core"
import { createRoot } from "@opentui/react"

function App() {
  return <text>Hello, OpenTUI!</text>
}

async function main() {
  const renderer = await createCliRenderer()
  createRoot(renderer).render(<App />)
}

main()

Project Templates

Minimal Template

Use case: Simple hello world, learning basics

import { createCliRenderer } from "@opentui/core"
import { TextRenderable } from "@opentui/core"

async function main() {
  const renderer = await createCliRenderer()

  const text = new TextRenderable("Hello, World!")
  renderer.getRoot().add(text)

  renderer.start()
}

main()

CLI Tool Template

Use case: Command-line tools with menus

import { createCliRenderer } from "@opentui/core"
import { BoxRenderable, TextRenderable } from "@opentui/core"

async function main() {
  const renderer = await createCliRenderer()

  const container = new BoxRenderable()
  container.setStyle({
    borderStyle: "double",
    padding: 1,
  })

  const title = new TextRenderable("My CLI Tool")
  title.setStyle({ textDecoration: "bold" })

  container.add(title)
  renderer.getRoot().add(container)

  renderer.start()
}

main()

Dashboard Template

Use case: Multi-panel dashboard applications

import { createCliRenderer } from "@opentui/core"
import { GroupRenderable, BoxRenderable, TextRenderable } from "@opentui/core"

async function main() {
  const renderer = await createCliRenderer()
  const root = renderer.getRoot()

  const app = new GroupRenderable()
  app.setStyle({
    flexDirection: "row",
    width: 80,
    height: 30,
  })

  // Sidebar
  const sidebar = new BoxRenderable()
  sidebar.setStyle({
    width: 20,
    borderStyle: "single",
  })
  sidebar.add(new TextRenderable("Sidebar"))

  // Main content
  const main = new BoxRenderable()
  main.setStyle({
    flexGrow: 1,
    borderStyle: "single",
  })
  main.add(new TextRenderable("Main Content"))

  app.add(sidebar)
  app.add(main)
  root.add(app)

  renderer.start()
}

main()

Form App Template

Use case: Data entry applications

import { createCliRenderer } from "@opentui/core"
import {
  GroupRenderable,
  BoxRenderable,
  TextRenderable,
  InputRenderable,
} from "@opentui/core"

async function main() {
  const renderer = await createCliRenderer()
  const root = renderer.getRoot()

  const form = new GroupRenderable()
  form.setStyle({
    flexDirection: "column",
    gap: 1,
    width: 60,
  })

  const title = new TextRenderable("User Registration")
  title.setStyle({ textDecoration: "bold" })

  const nameInput = new InputRenderable()
  nameInput.setPlaceholder("Name")

  const emailInput = new InputRenderable()
  emailInput.setPlaceholder("Email")

  const submitButton = new BoxRenderable()
  submitButton.setStyle({ borderStyle: "single" })
  submitButton.add(new TextRenderable("Submit"))

  form.add(title)
  form.add(nameInput)
  form.add(emailInput)
  form.add(submitButton)
  root.add(form)

  renderer.start()
}

main()

Component Library

Button Component

// components/Button.ts
import { BoxRenderable, TextRenderable } from "@opentui/core"

export interface ButtonOptions {
  label: string
  onClick?: () => void
  variant?: "primary" | "secondary" | "danger"
}

export class Button {
  private box: BoxRenderable

  constructor(options: ButtonOptions) {
    this.box = new BoxRenderable()
    this.setupStyles(options.variant)
    this.setupContent(options.label)
    this.setupEvents(options.onClick)
  }

  private setupStyles(variant: string = "primary") {
    const styles = {
      primary: {
        borderStyle: "single" as const,
        backgroundColor: new Color(100, 149, 237),
        foregroundColor: new Color(255, 255, 255),
      },
      secondary: {
        borderStyle: "single" as const,
        backgroundColor: new Color(50, 50, 50),
        foregroundColor: new Color(255, 255, 255),
      },
      danger: {
        borderStyle: "single" as const,
        backgroundColor: new Color(231, 76, 60),
        foregroundColor: new Color(255, 255, 255),
      },
    }

    const style = styles[variant as keyof typeof styles] || styles.primary
    this.box.setStyle(style)
  }

  private setupContent(label: string) {
    const text = new TextRenderable(label)
    this.box.add(text)
  }

  private setupEvents(onClick?: () => void) {
    if (onClick) {
      this.box.on("click", onClick)
    }
  }

  getRenderable() {
    return this.box
  }
}

Modal Component

// components/Modal.ts
import { BoxRenderable, TextRenderable, GroupRenderable } from "@opentui/core"

export class Modal {
  private overlay: BoxRenderable
  private content: BoxRenderable

  constructor() {
    this.overlay = new BoxRenderable()
    this.overlay.setStyle({
      position: "absolute",
      top: 0,
      left: 0,
      width: 80,
      height: 30,
      backgroundColor: new Color(0, 0, 0, 0.5),
    })

    this.content = new BoxRenderable()
    this.content.setStyle({
      borderStyle: "double",
      backgroundColor: new Color(30, 30, 30),
      padding: 2,
    })

    this.overlay.add(this.content)
  }

  setContent(component: any) {
    this.content.clear()
    this.content.add(component)
  }

  show() {
    this.overlay.setStyle({ display: "flex" })
  }

  hide() {
    this.overlay.setStyle({ display: "none" })
  }

  getRenderable() {
    return this.overlay
  }
}

Learning Paths

Beginner Path (1-2 weeks)

Week 1: Basics 1. Set up minimal project 2. Learn basic components (Text, Box) 3. Understand Yoga layout 4. Handle keyboard input 5. Style with colors

Week 2: Interactive 1. Use Input and Select components 2. Manage focus 3. Create simple forms 4. Handle events 5. Debug with console overlay

Projects:

• Hello World app
• Simple menu
• Basic form
• Counter app

Intermediate Path (2-4 weeks)

Week 3-4: Advanced 1. ScrollBox for lists 2. Animations with Timeline 2. Component composition 3. State management 4. Testing basics

Projects:

• Todo list
• File explorer
• Simple game (tic-tac-toe)
• Dashboard with multiple panels

Advanced Path (4-8 weeks)

Week 5-8: Production 1. Performance optimization 2. Advanced patterns 3. Error handling 4. Production deployment 5. Advanced testing

Projects:

• Text editor
• Terminal emulator
• Database viewer
• Complex dashboard

Examples Explorer

Available Examples

See .search-data/research/opentui/resources.md for a complete list of examples.

Key Examples: 1. OpenCode - AI coding agent (https://opencode.ai) 2. cftop - CloudFlare dashboard 3. critique - Git review tool 4. opentui-examples - Community examples

Running Examples

# Clone OpenTUI repo
git clone https://github.com/sst/opentui.git
cd opentui

# Install dependencies
bun install

# Run core examples
cd packages/core
bun run src/examples/index.ts

# Run React examples
cd packages/react
bun run dev

Best Practices

Project Organization

src/
├── main.tsx              # Entry point
├── app/                  # App components
│   ├── App.tsx
│   └── layout/
├── components/           # Reusable components
│   ├── ui/
│   └── features/
├── hooks/               # Custom hooks (React/SolidJS)
├── stores/              # State management
├── utils/               # Helper functions
└── types/               # TypeScript types

Component Design

1. Single Responsibility: Each component does one thing 2. Composition: Build complex UIs from simple components 3. Props Interface: Define clear props with TypeScript 4. Styling Consistency: Use themes and style utilities 5. Error Handling: Add error boundaries

Performance

1. Memoize expensive computations 2. Use efficient list rendering 3. Optimize re-renders 4. Profile performance 5. Test with realistic data

When to Use This Skill

Use /opentui-projects for:

• Creating new OpenTUI projects
• Choosing project templates
• Exploring examples
• Learning OpenTUI patterns
• Finding component libraries
• Best practices guidance

For core development help, use /opentui For React-specific help, use /opentui-react For SolidJS-specific help, use /opentui-solid

Resources

• Templates - Complete template catalog
• Examples - Curated example collection
• Learning Paths - Structured learning guides
• Best Practices - Production guidelines

Key Knowledge Sources

• create-tui: https://github.com/msmps/create-tui
• Awesome OpenTUI: https://github.com/msmps/awesome-opentui
• OpenTUI Examples: https://github.com/sst/opentui/tree/main/packages/core/src/examples
• Research: .search-data/research/opentui/

OpenTUI Examples Collection

Official Examples

Location

github.com/sst/opentui/tree/main/packages/core/src/examples/

Running Official Examples

# Clone repository
git clone https://github.com/sst/opentui.git
cd opentui

# Install dependencies
bun install

# Run core examples
cd packages/core
bun run src/examples/index.ts

Essential Examples by Category

1. Getting Started

Hello World

import { createCliRenderer } from "@opentui/core"
import { TextRenderable } from "@opentui/core"

async function main() {
  const renderer = await createCliRenderer()
  const text = new TextRenderable("Hello, OpenTUI!")
  renderer.getRoot().add(text)
  renderer.start()
}

main()

Concepts: Basic setup, rendering, root

---

Colors & Styling

import { createCliRenderer, Color } from "@opentui/core"
import { BoxRenderable, TextRenderable } from "@opentui/core"

async function main() {
  const renderer = await createCliRenderer()

  const box = new BoxRenderable()
  box.setStyle({
    backgroundColor: new Color(30, 30, 30),
    foregroundColor: new Color(255, 255, 255),
    borderStyle: "double",
    padding: 2,
  })

  const text = new TextRenderable("Styled Box")
  text.setStyle({ textDecoration: "bold" })

  box.add(text)
  renderer.getRoot().add(box)
  renderer.start()
}

main()

Concepts: Colors, borders, padding, text decoration

---

2. Layout Examples

Flexbox Layout

import { createCliRenderer } from "@opentui/core"
import { GroupRenderable, BoxRenderable, TextRenderable } from "@opentui/core"

async function main() {
  const renderer = await createCliRenderer()

  const container = new GroupRenderable()
  container.setStyle({
    flexDirection: "row",
    justifyContent: "space-between",
    alignItems: "center",
    gap: 2,
    width: 60,
  })

  const box1 = new BoxRenderable()
  box1.setStyle({ width: 10, backgroundColor: new Color(255, 0, 0) })
  box1.add(new TextRenderable("A"))

  const box2 = new BoxRenderable()
  box2.setStyle({ width: 10, backgroundColor: new Color(0, 255, 0) })
  box2.add(new TextRenderable("B"))

  const box3 = new BoxRenderable()
  box3.setStyle({ width: 10, backgroundColor: new Color(0, 0, 255) })
  box3.add(new TextRenderable("C"))

  container.add(box1)
  container.add(box2)
  container.add(box3)

  renderer.getRoot().add(container)
  renderer.start()
}

main()

Concepts: Yoga layout, flexDirection, justifyContent, gap

---

Nested Layouts

import { createCliRenderer } from "@opentui/core"
import { GroupRenderable, BoxRenderable } from "@opentui/core"

async function main() {
  const renderer = await createCliRenderer()

  const root = new GroupRenderable()
  root.setStyle({ flexDirection: "column", height: 20 })

  // Header row
  const header = new GroupRenderable()
  header.setStyle({ flexDirection: "row", height: 3 })
  const headerBox = new BoxRenderable()
  headerBox.setStyle({ backgroundColor: new Color(50, 50, 50) })
  header.add(headerBox)

  // Content row
  const content = new GroupRenderable()
  content.setStyle({ flexDirection: "row", flexGrow: 1 })

  const sidebar = new BoxRenderable()
  sidebar.setStyle({ width: 20, backgroundColor: new Color(30, 30, 30) })

  const main = new BoxRenderable()
  main.setStyle({ flexGrow: 1, backgroundColor: new Color(40, 40, 40) })

  content.add(sidebar)
  content.add(main)

  root.add(header)
  root.add(content)

  renderer.getRoot().add(root)
  renderer.start()
}

main()

Concepts: Nested groups, flexGrow, complex layouts

---

3. Input Handling

Keyboard Events

import { createCliRenderer } from "@opentui/core"
import { BoxRenderable, TextRenderable } from "@opentui/core"

async function main() {
  const renderer = await createCliRenderer()

  const status = new TextRenderable("Press any key...")

  renderer.on("key", (key) => {
    status.setText(`Key: ${key.name} ${key.ctrl ? "(Ctrl)" : ""}`)
  })

  const box = new BoxRenderable()
  box.add(status)
  renderer.getRoot().add(box)
  renderer.start()
}

main()

Concepts: Keyboard events, key names, modifiers

---

Interactive Form

import { createCliRenderer } from "@opentui/core"
import {
  GroupRenderable,
  BoxRenderable,
  TextRenderable,
  InputRenderable,
} from "@opentui/core"

async function main() {
  const renderer = await createCliRenderer()

  const form = new GroupRenderable()
  form.setStyle({ flexDirection: "column", gap: 1 })

  const nameInput = new InputRenderable()
  nameInput.setPlaceholder("Name")

  const emailInput = new InputRenderable()
  emailInput.setPlaceholder("Email")

  const submitBox = new BoxRenderable()
  submitBox.setStyle({ borderStyle: "single" })
  submitBox.add(new TextRenderable("Submit"))

  submitBox.on("click", () => {
    console.log(`Name: ${nameInput.getValue()}`)
    console.log(`Email: ${emailInput.getValue()}`)
  })

  form.add(nameInput)
  form.add(emailInput)
  form.add(submitBox)

  renderer.getRoot().add(form)
  renderer.start()
}

main()

Concepts: Input components, form handling, click events

---

4. Lists & Scroll

Scrollable List

import { createCliRenderer } from "@opentui/core"
import { ScrollBoxRenderable, TextRenderable } from "@opentui/core"

async function main() {
  const renderer = await createCliRenderer()

  const scrollBox = new ScrollBoxRenderable()
  scrollBox.setStyle({ width: 40, height: 15 })

  for (let i = 1; i <= 50; i++) {
    const text = new TextRenderable(`Item ${i}`)
    scrollBox.add(text)
  }

  renderer.getRoot().add(scrollBox)
  renderer.start()
}

main()

Concepts: ScrollBox, dynamic content

---

Interactive List

import { createCliRenderer } from "@opentui/core"
import {
  GroupRenderable,
  BoxRenderable,
  TextRenderable,
} from "@opentui/core"

async function main() {
  const renderer = await createCliRenderer()
  const items = ["Item 1", "Item 2", "Item 3", "Item 4", "Item 5"]
  let selectedIndex = 0

  const container = new GroupRenderable()
  container.setStyle({ flexDirection: "column" })

  const renderList = () => {
    container.clear()
    items.forEach((item, index) => {
      const box = new BoxRenderable()
      box.setStyle({
        backgroundColor:
          index === selectedIndex
            ? new Color(100, 149, 237)
            : new Color(30, 30, 30),
      })
      box.add(
        new TextRenderable(
          `${index === selectedIndex ? "> " : "  "}${item}`
        )
      )
      container.add(box)
    })
  }

  renderer.on("key", (key) => {
    if (key.name === "down") {
      selectedIndex = Math.min(selectedIndex + 1, items.length - 1)
      renderList()
    } else if (key.name === "up") {
      selectedIndex = Math.max(selectedIndex - 1, 0)
      renderList()
    }
  })

  renderList()
  renderer.getRoot().add(container)
  renderer.start()
}

main()

Concepts: List navigation, selection, dynamic rendering

---

5. Animations

Simple Animation

import { createCliRenderer, Timeline } from "@opentui/core"
import { BoxRenderable, TextRenderable } from "@opentui/core"

async function main() {
  const renderer = await createCliRenderer()

  const box = new BoxRenderable()
  box.setStyle({
    width: 20,
    height: 5,
    borderStyle: "single",
  })
  box.add(new TextRenderable("Animated!"))

  const timeline = new Timeline({
    duration: 2000,
    easing: (t) => t * (2 - t), // easeOutQuad
  })

  timeline.to(box, { backgroundColor: new Color(255, 0, 0) }, {
    onUpdate: () => renderer.render(),
  })

  timeline.play()

  renderer.getRoot().add(box)
  renderer.start()
}

main()

Concepts: Timeline, easing, property animation

---

Pulsing Effect

import { createCliRenderer, Timeline } from "@opentui/core"
import { BoxRenderable, TextRenderable } from "@opentui/core"

async function main() {
  const renderer = await createCliRenderer()

  const box = new BoxRenderable()
  box.setStyle({ width: 20, height: 5, borderStyle: "single" })
  box.add(new TextRenderable("Pulsing!"))

  const originalColor = new Color(30, 30, 30)
  const highlightColor = new Color(60, 60, 60)

  const timeline = new Timeline({
    duration: 1000,
    easing: (t) => t,
    loop: true,
  })

  timeline.to(
    box,
    { backgroundColor: highlightColor },
    {
      yoyo: true,
      from: { backgroundColor: originalColor },
      onUpdate: () => renderer.render(),
    }
  )

  timeline.play()

  renderer.getRoot().add(box)
  renderer.start()
}

main()

Concepts: Looping animations, yoyo effect

---

6. Real-World Examples

OpenCode (AI Coding Agent)

Repository: https://github.com/opencode-ai/opencode

Features:

• File explorer
• Code editor with syntax highlighting
• AI chat interface
• Multi-session support
• LSP integration

Run:

bun install opencode
opencode

---

cftop (CloudFlare Dashboard)

Repository: https://github.com/thedavejące/cftop

Features:

• Worker statistics
• Real-time metrics
• Interactive tables
• Navigation menus

---

critique (Git Review Tool)

Repository: https://github.com/kesuskese/critique

Features:

• Git diff visualization
• Review comments
• File navigation
• Status indicators

---

Community Examples

Component Libraries

Shadcn OpenTUI

URL: https://opentui.vercel.app/

Components:

• Button, Input, Select
• Modal, Dialog
• Table, List
• And more...

---

Tools & Utilities

opentui-spinner

Spinner component for loading states

opentui-ui

Reusable UI component library

---

Games & Demos

opentui-doom

DOOM running in the terminal using OpenTUI

present-drop

Festive terminal game

---

Learning Path Examples

Level 1: Beginner (1-2 days)

1. Hello World 2. Colors & Styling 3. Basic Layout 4. Simple Form

Level 2: Intermediate (3-5 days)

5. Keyboard Navigation 6. Scrollable Lists 7. Simple Animations 8. Modal Dialogs

Level 3: Advanced (1-2 weeks)

9. Complex Dashboard 10. Text Editor 11. Real-time Updates 12. Performance Optimization

---

Finding More Examples

GitHub Search

# Search for OpenTUI projects
# Query: "opentui" in:readme stars:>10

# Browse awesome list
# https://github.com/msmps/awesome-opentui

Official Resources

• OpenTUI Examples: /packages/core/src/examples/
• React Examples: /packages/react/README.md
• Awesome List: https://github.com/msmps/awesome-opentui

Contributing Examples

Have a great example? Share it!

1. Fork and create - Build your example 2. Add to awesome list - Submit PR to awesome-opentui 3. Share in community - Discord, Reddit, etc.

Reference

• OpenTUI Examples: https://github.com/sst/opentui/tree/main/packages/core/src/examples
• Awesome OpenTUI: https://github.com/msmps/awesome-opentui
• OpenCode: https://github.com/opencode-ai/opencode

OpenTUI Learning Paths

Overview

Structured learning paths for mastering OpenTUI, from beginner to advanced.

Path 1: Absolute Beginner (2-3 weeks)

Week 1: Foundation

Day 1-2: Setup & Basics

• [ ] Install Zig (required dependency)
• [ ] Install Bun or npm
• [ ] Set up TypeScript project
• [ ] Install @opentui/core
• [ ] Create "Hello World" app

Project: Minimal Hello World

import { createCliRenderer } from "@opentui/core"
import { TextRenderable } from "@opentui/core"

async function main() {
  const renderer = await createCliRenderer()
  const text = new TextRenderable("Hello, OpenTUI!")
  renderer.getRoot().add(text)
  renderer.start()
}

main()

---

Day 3-4: Core Components

• [ ] TextRenderable
• [ ] BoxRenderable
• [ ] GroupRenderable
• [ ] InputRenderable

Project: Simple Form

import { GroupRenderable, InputRenderable, BoxRenderable, TextRenderable } from "@opentui/core"

function createForm() {
  const form = new GroupRenderable()
  form.setStyle({ flexDirection: "column", gap: 1 })

  const name = new InputRenderable()
  name.setPlaceholder("Name")

  const submit = new BoxRenderable()
  submit.setStyle({ borderStyle: "single" })
  submit.add(new TextRenderable("Submit"))

  form.add(name)
  form.add(submit)
  return form
}

---

Day 5-7: Styling & Layout

• [ ] Yoga layout basics
• [ ] Colors (RGBA)
• [ ] Borders & padding
• [ ] Text decoration

Project: Styled Dashboard

const container = new GroupRenderable()
container.setStyle({
  flexDirection: "column",
  gap: 2,
  padding: 2,
})

---

Week 2: Interactivity

Day 8-10: Input Handling

• [ ] Keyboard events
• [ ] Mouse events
• [ ] Input component events
• [ ] Focus management

Project: Interactive Menu

renderer.on("key", (key) => {
  if (key.name === "down") {
    selectedIndex++
  }
})

---

Day 11-12: Lists & Scroll

• [ ] ScrollBoxRenderable
• [ ] Dynamic list rendering
• [ ] List navigation

Project: File List

const scrollBox = new ScrollBoxRenderable()
files.forEach(file => {
  scrollBox.add(new TextRenderable(file.name))
})

---

Day 13-14: State Management

• [ ] Component state
• [ ] Event-driven updates
• [ ] Data flow

Project: Todo List

let todos = []

function addTodo(text: string) {
  todos.push({ text, done: false })
  renderTodos()
}

---

Path 2: React Developer (2-3 weeks)

Prerequisites

• Familiarity with React
• JSX knowledge
• Hooks understanding

Week 1: React Integration

Day 1-2: Setup

• [ ] Install @opentui/react
• [ ] Configure React renderer
• [ ] Create basic React component

Project: React Hello World

import { createRoot } from "@opentui/react"

function App() {
  return <text>Hello from React!</text>
}

const renderer = await createCliRenderer()
createRoot(renderer).render(<App />)

---

Day 3-5: React Hooks

• [ ] useKeyboard
• [ ] useRenderer
• [ ] useTerminalDimensions
• [ ] useTimeline

Project: Interactive Counter

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

  useKeyboard((key) => {
    if (key.name === "up") setCount(c => c + 1)
  })

  return <text>Count: {count}</text>
}

---

Week 2: React Patterns

Day 6-8: Component Patterns

• [ ] Controlled components
• [ ] Compound components
• [ ] Render props
• [ ] Higher-order components

Project: Form Component

function Form() {
  const [values, setValues] = useState({})

  return (
    <box flexDirection="column">
      <input
        value={values.name}
        onChange={(v) => setValues({...values, name: v})}
      />
    </box>
  )
}

---

Day 9-10: State Management

• [ ] Context API
• [ ] Redux integration
• [ ] Zustand integration

Project: App with Context

const AppContext = createContext({})

function Provider({ children }) {
  const [state, setState] = useState({})
  return (
    <AppContext.Provider value={{ state, setState }}>
      {children}
    </AppContext.Provider>
  )
}

---

Week 3: Advanced React

Day 11-14: Advanced Topics

• [ ] Custom hooks
• [ ] Performance optimization
• [ ] Testing React components

Project: Full-featured Dashboard

---

Path 3: SolidJS Developer (2-3 weeks)

Week 1: SolidJS Basics

Day 1-3: Signals & Reactivity

• [ ] createSignal
• [ ] createMemo
• [ ] createEffect

Project: Signal Counter

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

  return <text>{count()}</text>
}

---

Day 4-7: SolidJS Components

• [ ] Component patterns
• [ ] Show/For/Switch
• [ ] Stores (createStore)

Project: Todo App with Signals

const [todos, setTodos] = createStore({
  items: []
})

---

Week 2: SolidJS + OpenTUI

Day 8-10: Integration

• [ ] useKeyboard (Solid)
• [ ] useRenderer (Solid)
• [ ] Component lifecycle

Project: SolidJS TUI App

---

Day 11-14: Advanced SolidJS

• [ ] Fine-grained reactivity
• [ ] Performance optimization
• [ ] Resource management

---

Path 4: Advanced Development (4-6 weeks)

Week 1-2: Advanced Layouts

Topics:

• Complex Yoga layouts
• Absolute positioning
• Responsive design
• Custom layout engines

Project:

Multi-panel IDE with:
- File explorer (left)
- Code editor (center)
- Output panel (bottom)
- Status bar (top)

---

Week 3-4: Advanced Features

Topics:

• Timeline animations
• Custom renderables
• Plugin architecture
• Event delegation

Project:

Animated dashboard with:
- Real-time data updates
- Smooth transitions
- Plugin system

---

Week 5-6: Production Ready

Topics:

• Error handling
• Performance profiling
• Memory management
• Testing strategies
• Production deployment

Project:

Production TUI app with:
- Comprehensive error handling
- 95%+ performance scores
- Full test coverage
- CLI distribution

---

Specialized Paths

Path A: Game Development (3-4 weeks)

Focus:

• Game loops
• Input handling
• Sprite rendering
• Collision detection
• Sound (if available)

Projects: 1. Snake game 2. Tetris clone 3. Roguelike basics

---

Path B: Data Visualization (2-3 weeks)

Focus:

• Chart rendering
• Graph layouts
• Real-time updates
• Data aggregation

Projects: 1. Line charts 2. Bar charts 3. System monitor

---

Path C: Developer Tools (3-4 weeks)

Focus:

• File system operations
• Process management
• API integration
• Complex workflows

Projects: 1. File manager 2. Process monitor 3. Database client

---

Learning Resources

Official

• OpenTUI Docs: .search-data/research/opentui/
• GitHub Examples: https://github.com/sst/opentui
• Source Code: https://github.com/sst/opentui/tree/main/packages

Community

• Awesome OpenTUI: https://github.com/msmps/awesome-opentui
• Discord (if available)
• Reddit r/opentui

Reference

• Yoga Layout: https://yogalayout.com/
• Terminal Escape Codes: https://gist.github.com/fnky/458734346b0e3e4d3852b706a7a0b4a6

---

Practice Projects

Beginner Projects

1. Hello World - Basic rendering 2. Counter - State management 3. Todo List - Forms & lists 4. Menu - Navigation 5. Form - Input handling

Intermediate Projects

6. File Browser - File system + lists 7. Chat App - Real-time updates 8. Music Player - Audio controls 9. Weather App - API integration 10. Note App - CRUD operations

Advanced Projects

11. Text Editor - Syntax highlighting 12. Terminal Emulator - Process handling 13. Database Client - SQL + tables 14. Git UI - Version control 15. IDE - Complex multi-panel

---

Assessment Checklist

Beginner

• [ ] Can create basic OpenTUI app
• [ ] Understands core components
• [ ] Can style components
• [ ] Handles keyboard input
• [ ] Manages simple state

Intermediate

• [ ] Builds complex layouts
• [ ] Uses lists & scrolling
• [ ] Implements forms
• [ ] Manages application state
• [ ] Handles errors gracefully

Advanced

• [ ] Optimizes performance
• [ ] Creates custom components
• [ ] Implements animations
• [ ] Tests applications
• [ ] Ships production apps

---

Tips for Success

1. Build projects, not tutorials - Create real apps 2. Read source code - Learn from OpenTUI internals 3. Join community - Share and learn 4. Teach others - Solidify knowledge 5. Experiment - Try new patterns

---

Next Steps After Learning

1. Contribute to OpenTUI 2. Publish component library 3. Create CLI tool 4. Share your projects 5. Mentor others

---

Reference

• OpenTUI Research: .search-data/research/opentui/
• Examples: references/EXAMPLES.md
• Templates: references/TEMPLATES.md

OpenTUI Best Practices

Project Structure

Recommended Directory Layout

my-opentui-app/
├── src/
│   ├── main.tsx                 # Entry point
│   ├── app/                     # Application components
│   │   ├── App.tsx
│   │   └── layout/
│   │       ├── AppShell.tsx
│   │       ├── Sidebar.tsx
│   │       └── Header.tsx
│   ├── components/              # Reusable components
│   │   ├── ui/                  # Basic UI components
│   │   │   ├── Button.tsx
│   │   │   ├── Input.tsx
│   │   │   └── Modal.tsx
│   │   └── features/            # Feature-specific components
│   │       └── auth/
│   │           └── LoginForm.tsx
│   ├── hooks/                   # Custom hooks (React/SolidJS)
│   │   ├── useKeyboard.ts
│   │   └── useNavigation.ts
│   ├── stores/                  # State management
│   │   └── useStore.ts
│   ├── utils/                   # Helper functions
│   │   ├── logger.ts
│   │   └── helpers.ts
│   ├── types/                   # TypeScript types
│   │   └── index.ts
│   └── constants/               # Constants
│       └── keys.ts
├── tests/                       # Tests
│   ├── unit/
│   └── integration/
├── package.json
├── tsconfig.json
└── README.md

Code Organization

File Naming

Components: PascalCase

Button.tsx
Modal.tsx
UserProfile.tsx

Hooks: camelCase with 'use' prefix

useKeyboard.ts
useNavigation.ts
useForm.ts

Utils: camelCase

logger.ts
formatDate.ts

Component Structure

Recommended order: 1. Imports 2. Types/Interfaces 3. Constants 4. Component function 5. Helper functions (inside or outside)

// 1. Imports
import { BoxRenderable, TextRenderable } from "@opentui/core"
import { useKeyboard } from "@opentui/react"

// 2. Types
interface ButtonProps {
  label: string
  onClick?: () => void
}

// 3. Component
export function Button(props: ButtonProps) {
  // Component logic
  const handleClick = () => {
    props.onClick?.()
  }

  return (
    <box onClick={handleClick}>
      <text>{props.label}</text>
    </box>
  )
}

Styling Best Practices

Use Theme Objects

// constants/theme.ts
export const theme = {
  colors: {
    primary: { r: 100, g: 149, b: 237 },
    secondary: { r: 50, g: 50, b: 50 },
    success: { r: 46, g: 204, b: 113 },
    danger: { r: 231, g: 76, b: 60 },
  },
  spacing: {
    xs: 1,
    sm: 2,
    md: 3,
    lg: 4,
  },
}

// Usage
import { theme } from "./constants/theme"

<box
  backgroundColor={theme.colors.primary}
  padding={theme.spacing.md}
>

Consistent Style Props

// Good: reusable style function
const cardStyle = () => ({
  borderStyle: "single" as const,
  backgroundColor: theme.colors.secondary,
  padding: theme.spacing.sm,
})

// Usage
<box style={cardStyle()}>

// Bad: inline styles everywhere
<box borderStyle="single" backgroundColor={{r:50,g:50,b:50}} padding={2}>

Style Utilities

// utils/styles.ts
export const styles = {
  card: (variant: "primary" | "secondary") => ({
    borderStyle: "single" as const,
    backgroundColor:
      variant === "primary"
        ? theme.colors.primary
        : theme.colors.secondary,
    padding: theme.spacing.sm,
  }),

  button: (size: "sm" | "md" | "lg") => ({
    padding: size === "sm" ? 1 : size === "md" ? 2 : 3,
  }),
}

State Management

Choose the Right Tool

State Organization

// stores/useStore.ts (Zustand example)
import { create } from "zustand"

interface AppState {
  // UI state
  sidebarOpen: boolean
  setSidebarOpen: (open: boolean) => void

  // Data state
  users: User[]
  fetchUsers: () => Promise<void>

  // View state
  currentView: "dashboard" | "settings"
  setCurrentView: (view: "dashboard" | "settings") => void
}

export const useStore = create<AppState>((set, get) => ({
  // Initial state
  sidebarOpen: true,
  users: [],
  currentView: "dashboard",

  // Actions
  setSidebarOpen: (open) => set({ sidebarOpen: open }),

  fetchUsers: async () => {
    const users = await api.getUsers()
    set({ users })
  },

  setCurrentView: (view) => set({ currentView: view }),
}))

Error Handling

Error Boundaries (React)

// components/ErrorBoundary.tsx
import { ErrorBoundary } from "solid-js" // or React equivalent

export function SafeComponent(props: { children: any }) {
  return (
    <ErrorBoundary
      fallback={(err) => (
        <box borderStyle="double" padding={2}>
          <text decoration="bold">Error:</text>
          <text>{err.message}</text>
          <text>Press Ctrl+C to exit</text>
        </box>
      )}
    >
      {props.children}
    </ErrorBoundary>
  )
}

Try-Catch in Async

async function loadData() {
  try {
    const data = await fetch("/api/data")
    return await data.json()
  } catch (error) {
    console.error("Failed to load data:", error)
    // Show error to user
    showError("Failed to load data")
  }
}

Performance

Memoization

// Good: memoize expensive computation
const sortedList = createMemo(() =>
  items().sort((a, b) => a.name.localeCompare(b.name))
)

// Bad: recompute on every render
const sortedList = items().sort((a, b) => a.name.localeCompare(b.name))

List Rendering

// Good: Use <For> in SolidJS
<For each={items()}>
  {(item) => <text>{item.name}</text>}
</For>

// Good: Use key prop in React
{items().map((item) => (
  <text key={item.id}>{item.name}</text>
))}

Avoid Unnecessary Re-renders

// Good: Split into separate components
function List() {
  const [items] = useStore(state => state.items)

  return (
    <For each={items}>
      {(item) => <ListItem item={item} />}
    </For>
  )
}

function ListItem(props: { item: any }) {
  // Only re-renders when props.item changes
  return <text>{props.item.name}</text>
}

Testing

Test Structure

tests/
├── unit/
│   ├── components/
│   │   └── Button.test.tsx
│   └── utils/
│       └── formatDate.test.ts
└── integration/
    └── LoginForm.test.tsx

Test Naming

describe("Button", () => {
  it("should render label", () => {
    // Test
  })

  it("should call onClick when clicked", () => {
    // Test
  })

  it("should not call onClick when disabled", () => {
    // Test
  })
})

Test Best Practices

1. Test user behavior, not implementation 2. One assertion per test when possible 3. Use descriptive test names 4. Mock external dependencies 5. Test edge cases

Documentation

Component Documentation

/**
 * Button component for user actions
 *
 * @param label - Text to display on button
 * @param onClick - Callback when button is clicked
 * @param variant - Visual style variant
 *
 * @example
 * ```tsx
 * <Button
 *   label="Submit"
 *   onClick={() => console.log("clicked")}
 *   variant="primary"
 * />
 * ```
 */
export function Button(props: ButtonProps) {
  // ...
}

README Structure

# My OpenTUI App

## Description
Brief description of what the app does

## Installation
\`\`\`bash
bun install
\`\`\`

## Usage
\`\`\`bash
bun run start
\`\`\`

## Features
- Feature 1
- Feature 2

## Keyboard Shortcuts
- Ctrl+C - Exit
- Ctrl+S - Save

## Development
\`\`\`bash
bun run dev
\`\`\`

Git Practices

Commit Messages

feat: add user authentication
fix: resolve layout issue on small terminals
docs: update installation guide
refactor: simplify form handling
test: add tests for Button component

.gitignore

node_modules/
dist/
.env
.DS_Store
*.log

Deployment

Package.json Scripts

{
  "scripts": {
    "dev": "bun run src/main.tsx",
    "build": "tsc",
    "start": "node dist/main.js",
    "test": "vitest",
    "lint": "eslint src/",
    "format": "prettier --write src/"
  }
}

Distribution

# Build
bun run build

# Package
tar czf my-app.tar.gz dist/

# Or install globally
bun link

Security

Input Validation

function validateEmail(email: string): boolean {
  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
  return emailRegex.test(email)
}

Sanitization

// Sanitize file paths
function sanitizePath(path: string): string {
  return path.replace(/\.\./g, "").replace(/~/g, "")
}

Accessibility

Keyboard Navigation

// Always provide keyboard alternatives
function Button(props: ButtonProps) {
  useKeyboard((key) => {
    if (key.name === "enter" || key.name === " ") {
      props.onClick()
    }
  })

  return <box onClick={props.onClick}>{props.label}</box>
}

Focus Indicators

// Show focus clearly
function FocusableBox(props: { children: any }) {
  const [focused, setFocused] = useState(false)

  return (
    <box
      borderStyle={focused ? "double" : "single"}
      onFocus={() => setFocused(true)}
      onBlur={() => setFocused(false)}
    >
      {props.children}
    </box>
  )
}

Debugging

Enable Console Overlay

import { consoleOverlay } from "@opentui/core"

async function main() {
  const renderer = await createCliRenderer()

  if (process.env.DEBUG) {
    renderer.attach(consoleOverlay())
  }

  // Now console.log() appears in terminal
  console.log("Debug mode enabled")
}

Performance Profiling

function profileRender(component: any, label: string) {
  const start = performance.now()

  renderer.getRoot().add(component)
  renderer.render()

  const end = performance.now()
  console.log(`${label} rendered in ${end - start}ms`)
}

Common Pitfalls

Don't Mix Concerns

// Bad: UI and business logic mixed
function BadComponent() {
  const [users, setUsers] = useState([])

  useEffect(() => {
    fetch("/api/users")
      .then(res => res.json())
      .then(data => setUsers(data))
  }, [])

  return <text>{users.length} users</text>
}

// Good: Separated concerns
function GoodComponent() {
  const users = useUsers() // Custom hook handles data

  return <UserCount count={users.length} />
}

Avoid Prop Drilling

// Bad: Prop drilling
function App() {
  const [theme, setTheme] = useState("dark")
  return <Sidebar theme={theme} setTheme={setTheme} />
}

// Good: Context
function App() {
  return (
    <ThemeProvider>
      <Sidebar />
    </ThemeProvider>
  )
}

Resources

• OpenTUI Docs: https://github.com/sst/opentui
• Yoga Layout: https://yogalayout.com/
• TypeScript Best Practices: https://github.com/typescript-cheatsheets/react

OpenTUI Project Templates

Template Overview

Template: Minimal

Purpose

Quick start for learning OpenTUI basics

Structure

minimal-app/
├── package.json
├── tsconfig.json
└── src/
    └── main.tsx

Files

package.json

{
  "name": "minimal-opentui",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "start": "bun run src/main.tsx"
  },
  "dependencies": {
    "@opentui/core": "latest"
  }
}

src/main.tsx

import { createCliRenderer } from "@opentui/core"
import { TextRenderable } from "@opentui/core"

async function main() {
  const renderer = await createCliRenderer()

  const text = new TextRenderable("Hello, OpenTUI!")
  renderer.getRoot().add(text)

  renderer.start()
}

main()

Template: Basic CLI

Purpose

Command-line tools with menus and navigation

Structure

cli-app/
├── package.json
├── tsconfig.json
└── src/
    ├── main.tsx
    ├── menu.tsx
    └── components/
        └── MenuItem.tsx

Files

src/menu.tsx

import { GroupRenderable, BoxRenderable, TextRenderable } from "@opentui/core"

export function createMenu(items: string[], onSelect: (index: number) => void) {
  const container = new GroupRenderable()
  container.setStyle({
    flexDirection: "column",
    gap: 1,
  })

  let selectedIndex = 0

  items.forEach((item, index) => {
    const menuItem = new BoxRenderable()
    menuItem.setStyle({
      borderStyle: "single",
      padding: 1,
    })

    const text = new TextRenderable(item)
    menuItem.add(text)
    container.add(menuItem)
  })

  return container
}

src/main.tsx

import { createCliRenderer } from "@opentui/core"
import { createMenu } from "./menu"

async function main() {
  const renderer = await createCliRenderer()

  const menu = createMenu(
    ["Option 1", "Option 2", "Option 3", "Exit"],
    (index) => {
      console.log("Selected:", index)
      if (index === 3) {
        renderer.destroy()
        process.exit(0)
      }
    }
  )

  renderer.getRoot().add(menu)
  renderer.start()
}

main()

Template: Dashboard

Purpose

Multi-panel dashboard applications with sidebar

Structure

dashboard-app/
├── package.json
├── tsconfig.json
└── src/
    ├── main.tsx
    ├── layout/
    │   ├── AppShell.tsx
    │   ├── Sidebar.tsx
    │   └── MainPanel.tsx
    └── widgets/
        ├── StatsWidget.tsx
        └── ListWidget.tsx

Files

src/layout/AppShell.tsx

import { GroupRenderable, BoxRenderable } from "@opentui/core"

export function createAppShell() {
  const shell = new GroupRenderable()
  shell.setStyle({
    flexDirection: "column",
    width: 80,
    height: 30,
  })

  // Header
  const header = new BoxRenderable()
  header.setStyle({
    height: 3,
    borderStyle: "double",
  })

  // Content area
  const content = new GroupRenderable()
  content.setStyle({
    flexDirection: "row",
    flexGrow: 1,
  })

  shell.add(header)
  shell.add(content)

  return { shell, header, content }
}

src/layout/Sidebar.tsx

import { BoxRenderable, TextRenderable } from "@opentui/core"

export function createSidebar() {
  const sidebar = new BoxRenderable()
  sidebar.setStyle({
    width: 20,
    borderStyle: "single",
  })

  const title = new TextRenderable("Navigation")
  title.setStyle({ textDecoration: "bold" })
  sidebar.add(title)

  return sidebar
}

src/main.tsx

import { createCliRenderer } from "@opentui/core"
import { createAppShell } from "./layout/AppShell"
import { createSidebar } from "./layout/Sidebar"

async function main() {
  const renderer = await createCliRenderer()
  const { shell, content } = createAppShell()

  const sidebar = createSidebar()
  content.add(sidebar)

  renderer.getRoot().add(shell)
  renderer.start()
}

main()

Template: Form App

Purpose

Data entry applications with validation

Structure

form-app/
├── package.json
├── tsconfig.json
└── src/
    ├── main.tsx
    ├── forms/
    │   ├── Form.tsx
    │   ├── Field.tsx
    │   └── Validation.tsx
    └── components/
        └── Input.tsx

Files

src/forms/Form.tsx

import { GroupRenderable, BoxRenderable, InputRenderable, TextRenderable } from "@opentui/core"

export interface FormField {
  name: string
  label: string
  type: "text" | "password" | "email"
  required: boolean
}

export function createForm(fields: FormField[], onSubmit: (data: any) => void) {
  const form = new GroupRenderable()
  form.setStyle({
    flexDirection: "column",
    gap: 1,
    width: 60,
  })

  const inputs: Map<string, InputRenderable> = new Map()

  fields.forEach(field => {
    const label = new TextRenderable(`${field.label}:`)
    if (field.required) {
      label.setStyle({ textDecoration: "bold" })
    }

    const input = new InputRenderable()
    if (field.type === "password") {
      // Configure password mode (if supported)
    }
    input.setPlaceholder(`Enter ${field.label.toLowerCase()}`)

    inputs.set(field.name, input)

    form.add(label)
    form.add(input)
  })

  // Submit button
  const submitButton = new BoxRenderable()
  submitButton.setStyle({ borderStyle: "single" })
  submitButton.add(new TextRenderable("Submit"))
  submitButton.on("click", () => {
    const data: any = {}
    inputs.forEach((input, name) => {
      data[name] = input.getValue()
    })
    onSubmit(data)
  })

  form.add(submitButton)

  return form
}

src/main.tsx

import { createCliRenderer } from "@opentui/core"
import { createForm } from "./forms/Form"

async function main() {
  const renderer = await createCliRenderer()

  const form = createForm(
    [
      { name: "username", label: "Username", type: "text", required: true },
      { name: "email", label: "Email", type: "email", required: true },
      { name: "password", label: "Password", type: "password", required: true },
    ],
    (data) => {
      console.log("Form submitted:", data)
      renderer.destroy()
      process.exit(0)
    }
  )

  renderer.getRoot().add(form)
  renderer.start()
}

main()

Template: Editor

Purpose

Text editing with syntax highlighting

Structure

editor-app/
├── package.json
├── tsconfig.json
└── src/
    ├── main.tsx
    ├── editor/
    │   ├── Editor.tsx
    │   ├── Buffer.tsx
    │   └── Cursor.tsx
    └── modes/
        ├── NormalMode.tsx
        └── InsertMode.tsx

Files

src/editor/Buffer.tsx

import { ScrollBoxRenderable, TextRenderable } from "@opentui/core"

export class Buffer {
  private scrollBox: ScrollBoxRenderable
  private lines: string[] = []

  constructor() {
    this.scrollBox = new ScrollBoxRenderable()
    this.scrollBox.setStyle({ width: 80, height: 20 })
  }

  load(content: string) {
    this.lines = content.split("\n")
    this.render()
  }

  render() {
    this.scrollBox.clear()
    this.lines.forEach(line => {
      this.scrollBox.add(new TextRenderable(line))
    })
  }

  insertLine(index: number, line: string) {
    this.lines.splice(index, 0, line)
    this.render()
  }

  getRenderable() {
    return this.scrollBox
  }
}

src/editor/Editor.tsx

import { GroupRenderable, BoxRenderable } from "@opentui/core"
import { Buffer } from "./Buffer"

export function createEditor() {
  const editor = new GroupRenderable()
  editor.setStyle({
    flexDirection: "column",
    width: 80,
    height: 30,
  })

  // Status bar
  const statusBar = new BoxRenderable()
  statusBar.setStyle({
    height: 2,
    borderStyle: "single",
  })

  // Buffer
  const buffer = new Buffer()

  editor.add(buffer.getRenderable())
  editor.add(statusBar)

  return { editor, buffer, statusBar }
}

Template: Game

Purpose

Simple games with animation

Structure

game-app/
├── package.json
├── tsconfig.json
└── src/
    ├── main.tsx
    ├── game/
    │   ├── Game.tsx
    │   ├── Loop.tsx
    │   └── Input.tsx
    └── entities/
        └── Player.tsx

Files

src/game/Loop.tsx

import { Timeline } from "@opentui/core"

export class GameLoop {
  private fps: number
  private interval: number
  private running: boolean = false

  constructor(fps: number = 60) {
    this.fps = fps
    this.interval = 1000 / fps
  }

  start(update: () => void) {
    this.running = true
    let lastTime = Date.now()

    const loop = () => {
      if (!this.running) return

      const now = Date.now()
      const delta = now - lastTime

      if (delta >= this.interval) {
        update()
        lastTime = now
      }

      setTimeout(loop, 0)
    }

    loop()
  }

  stop() {
    this.running = false
  }
}

src/game/Game.tsx

import { BoxRenderable, TextRenderable } from "@opentui/core"
import { GameLoop } from "./Loop"

export function createGame() {
  const canvas = new BoxRenderable()
  canvas.setStyle({
    width: 40,
    height: 20,
    borderStyle: "single",
  })

  const score = new TextRenderable("Score: 0")
  canvas.add(score)

  const loop = new GameLoop(30)

  loop.start(() => {
    // Game logic here
    score.setText(`Score: ${Math.floor(Math.random() * 100)}`)
  })

  return canvas
}

Custom Templates

Creating Your Own Template

# Create template directory
mkdir my-opentui-template
cd my-opentui-template

# Initialize
bun init -y

# Add OpenTUI
bun add @opentui/core

# Create your template structure
mkdir -p src/{components,utils,types}

# Add template files
# ...

# Package as template
# Publish to npm or use locally

Using Custom Template

# From local directory
bun create tui my-app --template ./my-opentui-template

# From npm (if published)
bun create tui my-app --template my-package-name

Reference

• create-tui: https://github.com/msmps/create-tui
• OpenTUI Examples: https://github.com/sst/opentui/tree/main/packages/core/src/examples
• Awesome OpenTUI: https://github.com/msmps/awesome-opentui