Core Configuration

Renderer Configuration

createCliRenderer Options

import { createCliRenderer, ConsolePosition } from "@opentui/core"

const renderer = await createCliRenderer({
  // Rendering
  targetFPS: 60,                    // Target frames per second (default: 60)
  
  // Behavior
  exitOnCtrlC: true,                // Exit on Ctrl+C (default: true)
  
  // Console overlay
  consoleOptions: {
    position: ConsolePosition.BOTTOM,  // BOTTOM | TOP | LEFT | RIGHT
    sizePercent: 30,                   // Percentage of screen
    colorInfo: "#00FFFF",
    colorWarn: "#FFFF00",
    colorError: "#FF0000",
    colorDebug: "#888888",
    startInDebugMode: false,
  },
  
  // Lifecycle
  onDestroy: () => {
    // Cleanup callback
  },
})

Environment Variables

OpenTUI respects several environment variables for configuration and debugging.

Debug & Development

Variable	Type	Default	Description
`OTUI_DEBUG`	boolean	false	Enable debug mode, capture raw input
`OTUI_DEBUG_FFI`	boolean	false	Debug logging for FFI bindings
`OTUI_TRACE_FFI`	boolean	false	Tracing for FFI bindings
`OTUI_SHOW_STATS`	boolean	false	Show debug overlay at startup
`OTUI_DUMP_CAPTURES`	boolean	false	Dump captured output on exit

Console

Variable	Type	Default	Description
`OTUI_USE_CONSOLE`	boolean	true	Enable console capture
`SHOW_CONSOLE`	boolean	false	Show console at startup

Rendering

Variable	Type	Default	Description
`OTUI_NO_NATIVE_RENDER`	boolean	false	Disable ANSI output (for debugging)
`OTUI_USE_ALTERNATE_SCREEN`	boolean	true	Use alternate screen buffer
`OTUI_OVERRIDE_STDOUT`	boolean	true	Override stdout stream

Terminal Capabilities

Variable	Type	Default	Description
`OPENTUI_NO_GRAPHICS`	boolean	false	Disable Kitty graphics protocol
`OPENTUI_FORCE_UNICODE`	boolean	false	Force Mode 2026 Unicode support
`OPENTUI_FORCE_WCWIDTH`	boolean	false	Use wcwidth for character width
`OPENTUI_FORCE_NOZWJ`	boolean	false	Disable ZWJ emoji joining
`OPENTUI_FORCE_EXPLICIT_WIDTH`	string	-	Force explicit width ("true"/"false")

Tree-sitter (Syntax Highlighting)

Variable	Type	Default	Description
`OTUI_TS_STYLE_WARN`	boolean	false	Warn on missing syntax styles
`OTUI_TREE_SITTER_WORKER_PATH`	string	""	Custom tree-sitter worker path

XDG Paths

Variable	Type	Default	Description
`XDG_CONFIG_HOME`	string	""	User config directory
`XDG_DATA_HOME`	string	""	User data directory

Usage Examples

Development Mode

# Show debug overlay and console
OTUI_SHOW_STATS=true SHOW_CONSOLE=true bun run src/index.ts

# Debug FFI issues
OTUI_DEBUG_FFI=true OTUI_TRACE_FFI=true bun run src/index.ts

# Disable native rendering for testing
OTUI_NO_NATIVE_RENDER=true bun run src/index.ts

Terminal Compatibility

# Force wcwidth for problematic terminals
OPENTUI_FORCE_WCWIDTH=true bun run src/index.ts

# Disable graphics for SSH sessions
OPENTUI_NO_GRAPHICS=true bun run src/index.ts

Project Setup

package.json

{
  "name": "my-tui-app",
  "type": "module",
  "scripts": {
    "start": "bun run src/index.ts",
    "dev": "bun --watch run src/index.ts",
    "test": "bun test"
  },
  "dependencies": {
    "@opentui/core": "latest"
  },
  "devDependencies": {
    "@types/bun": "latest",
    "typescript": "latest"
  }
}

tsconfig.json

{
  "compilerOptions": {
    "lib": ["ESNext"],
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "skipLibCheck": true,
    "noEmit": true,
    "types": ["bun-types"]
  },
  "include": ["src/**/*"]
}

Building Native Code

Native code changes require rebuilding:

# From repo root (if developing OpenTUI itself)
bun run build

# Zig is required for native compilation
# Install: https://ziglang.org/learn/getting-started/

Note: TypeScript changes do NOT require building. Bun runs TypeScript directly.

4.3 KiB Raw Blame History