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
3. Component composition
4. State management
5. 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](references/TEMPLATES.md) - Complete template catalog
• [Examples](references/EXAMPLES.md) - Curated example collection
• [Learning Paths](references/LEARNING.md) - Structured learning guides
• [Best Practices](references/PRACTICES.md) - 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/