reactive-termui

[!WARNING] Work in progress. APIs and runtime behavior are still evolving.

reactive-termui is a Vue-first runtime for building interactive CLI apps with components and SFC-style authoring. It stays close to Ink's API model and reuses Ink internals where practical.

pnpm add reactive-termui vue -D

API Alignment

reactive-termui keeps its public API very close to Ink. If you already know Ink, the same component/hook mental model should carry over. RenderOptions.concurrent is currently unsupported.

Runtime APIs

• render: mount a Vue CLI app into terminal streams and return an app instance (rerender, unmount, clear, waitUntilExit).
• renderToString: run the same layout pipeline without an interactive session and return a plain string snapshot.
• measureElement: read Yoga-computed size and position from an Ink node, useful for layout-aware logic.

Primitives

• Box: flex layout container for spacing, alignment, borders, background, and overflow control.
• Text: styled terminal text with wrapping and accessibility labels.
• Static: render immutable lines above dynamic output (great for logs/history).
• Transform: post-process child output text before it is printed.
• Newline: insert explicit line breaks.
• Spacer: consume remaining layout space for alignment and separation.

Composables

• useApp: access app-level controls such as exit() and render-flush waiting.
• useStdin / useStdout / useStderr: access terminal streams and stream-related runtime state.
• useWindowSize: reactively track terminal width/height (columns, rows).
• useIsScreenReaderEnabled: read whether accessibility mode is enabled.
• useInput / usePaste: handle keyboard input and paste events in reactive Vue logic.
• useCursor: control cursor visibility and cursor position behavior.
• useFocus / useFocusManager: register focusable elements and move focus between them.
• useBoxMetrics: read measured box width/height/offset from a Box ref.

Other Exports

• kittyFlags / kittyModifiers: constants/helpers for interpreting Kitty keyboard protocol data.
• RenderOptions.kittyKeyboard: controls Kitty keyboard protocol mode (enabled, disabled, auto).
• RenderOptions.concurrent: currently unsupported.

Render Options

• stdout / stdin / stderr: route rendering and input through custom streams instead of process defaults.
• debug: print full frames directly for debugging instead of regular interactive diffing.
• exitOnCtrlC: automatically exit when Ctrl+C is pressed.
• patchConsole: patch console.* so logs do not break the active interactive frame.
• interactive: toggle interactive behavior (input listeners, resize updates, live redraw).
• onRender: callback with per-frame render timing metrics.
• maxFps: cap render frequency (default aligned with Ink: 30).
• incrementalRendering: choose incremental frame updates vs non-incremental rendering (default aligned with Ink: false).
• isScreenReaderEnabled: switch to screen-reader-friendly output behavior.
• kittyKeyboard: configure Kitty keyboard protocol mode.
• concurrent: unsupported.

Known Differences

• React concurrent features: unsupported. Ink's concurrent mode depends on React Fiber scheduling.
• Compatibility coverage: partial. Most public APIs are aligned, but some runtime edge cases may still differ.

Why ?

reactive-termui is inspired by Ink, with a simple goal: build CLI apps with Vue (including Vue SFC authoring) while keeping Ink's mental model and API shape as close as possible.

Complex CLI interactions become hard to maintain quickly when everything is ad-hoc string rendering. This project is built around stronger component structure and reuse, so larger flows can share UI pieces, state logic, and interaction patterns in a cleaner way.

I also do most UI work in Vue, so I want the same SFC + composable workflow in terminal apps. That keeps development style consistent across web UI and CLI UI, and makes iteration faster.

The focus remains Ink API familiarity, not inventing a different terminal UI model. Primitives, composables, runtime options, and exported types stay aligned with Ink unless a React-only concept has no honest Vue equivalent.

Credits

• Ink: primary inspiration and the reference architecture for this project. reactive-termui reuses Ink internals wherever possible and follows Ink behavior as closely as possible.
• vue-termui: a valuable learning reference for Vue-based terminal UI design and ecosystem direction.

License

MIT License © jinghaihan