Skip to main content

​
Overview

The renderer module provides the core rendering engine for Bunli TUI applications. It manages the OpenTUI renderer lifecycle, handles alternate screen buffers, and provides React integration.

​
Imports

import { runTuiRender } from '@bunli/runtime/renderer'
import type { RunTuiRenderArgs, TuiRenderOptions } from '@bunli/runtime'

​
runTuiRender

Runs a TUI render with the provided command and options. 
async function runTuiRender(args: RunTuiRenderArgs): Promise<void>

​
Parameters

​
args
RunTuiRenderArgs
required
Render configuration

​
Example

import { runTuiRender } from '@bunli/runtime/renderer'
import { App } from './app'

await runTuiRender({
  command: {
    render: () => <App />
  },
  rendererOptions: {
    bufferMode: 'alternate',
    exitOnCtrlC: true,
    targetFps: 30
  }
})

​
TuiRenderOptions

Configuration options for the OpenTUI renderer.

​
Fields

​
exitOnCtrlC
boolean
default:"true"
Whether to exit the application on Ctrl+C
​
targetFps
number
default:"30"
Target frames per second for rendering
​
enableMouseMovement
boolean
default:"true"
Enable mouse movement events
​
useMouse
boolean
default:"false"
Enable mouse input support
​
bufferMode
'alternate' | 'standard'
default:"'standard'"
Terminal buffer mode:
  • alternate: Full-screen alternate buffer (clears screen)
  • standard: Render in the main buffer (inline with terminal history)

​
Example

const options: TuiRenderOptions = {
  bufferMode: 'alternate',
  exitOnCtrlC: true,
  targetFps: 60,
  useMouse: true,
  enableMouseMovement: true
}

​
Runtime Events

The renderer emits lifecycle events through the transport:
​
runtime.renderer.started
RuntimeRendererStartedEvent
Emitted when the renderer starts
​
runtime.renderer.destroyed
RuntimeRendererDestroyedEvent
Emitted when the renderer is destroyed
​
runtime.renderer.missing-render
RuntimeRendererMissingRenderEvent
Emitted when command.render is missing or invalid

​
AppRuntimeProvider

React context provider for runtime features. 
import { AppRuntimeProvider } from '@bunli/runtime'

function App() {
  return (
    <AppRuntimeProvider>
      <YourApp />
    </AppRuntimeProvider>
  )
}
The AppRuntimeProvider is automatically included by runTuiRender, so you typically don’t need to use it directly.

​
Best Practices

Buffer Mode Selection

  • Use alternate for full-screen applications (dashboards, editors)
  • Use standard for inline output that should remain in terminal history

Frame Rate

  • Default 30 FPS is suitable for most applications
  • Increase to 60 FPS for smooth animations
  • Lower FPS reduces CPU usage for static content

Error Handling

  • Always provide a valid render function
  • Handle component errors with React error boundaries
  • Use transport to monitor renderer lifecycle events

Build docs developers (and LLMs) love

Get started for freeTalk to us