TerminalTUI: A TypeScript TUI Framework with File-Based Routing + SSH Hosting

TerminalTUI is a TypeScript TUI framework that feels like Next.js + React, but the output runs in any terminal. It ships with 30+ pre-built components, a 12-column responsive grid, spatial arrow-key navigation, file-based routing, reactive state, 10 color themes, and one-line SSH hosting. 2,185+ tests. One runtime dep: esbuild. Install with:

npx terminaltui init my-app
cd my-app
npm run dev                # hot reload
npx terminaltui host       # expose it behind SSH

TL;DR

• TypeScript TUI framework with React-like ergonomics and Next.js-style routing.
• 30+ components (tables, modals, sparklines, forms) + 12-column grid + 10 themes.
• Spatial arrow-key navigation — focus moves in visual direction, not DOM order.
• One-line SSH hosting — npx terminaltui host and users ssh into your app.
• 2,185+ tests, minimal dependencies.

Why another TUI library

I live in the terminal. My editor is there. My shell is there. Over the past year I've been slowly moving more of my tooling into terminal-native apps — and I kept hitting the same wall with every TUI library I tried.

• Either it was "bring your own render loop" (raw escape-sequence territory).
• Or it was very opinionated about layout in a way that didn't match how I think about UI.
• Or it had routing but no focus-management, or focus but no routing, or both but no testing story.

I wanted the terminal equivalent of the Next.js + React combo: declarative components, a router, reactive state, and a sane default for focus and keyboard nav. That didn't exist, so TerminalTUI is it.

What's in the framework

| Feature | Summary | |---|---| | Components | 30+ pre-built: buttons, inputs, tables, modals, tabs, menus, progress bars, sparklines | | Grid | 12-column responsive grid that reflows on terminal resize | | Navigation | Spatial arrow-key focus (visual direction, not DOM order) | | Themes | 10 built-in color themes, hot-switchable at runtime | | ASCII art | Declarative figlet-style banner engine | | Routing | File-based, same mental model as Next.js app router | | State | Reactive state management built in | | Forms | With validation | | SSH | One-line hosting so users ssh into your app | | Testing | Headless emulator + 2,185+ tests |

The spatial-nav feature that sold me on writing my own framework

Here's the feature I missed most from every other TUI library. Arrow keys move focus in the visual direction, not in DOM order.

If your form has two columns of inputs, Up and Down walk a column, Left and Right switch columns. Tab still walks DOM order for a11y. It sounds obvious and almost no TUI library does it correctly, because implementing it requires holding a 2D grid of focusable regions and picking the best candidate in the requested direction — not just iterating a list.

The SSH hosting feature

This is my favorite part. You can take any TerminalTUI app and host it over SSH with one line of config:

// terminaltui.config.ts
export default {
  ssh: { port: 2222, hostKeyPath: "./host_key" }
};

Then npx terminaltui host. Users ssh user@your-host -p 2222 and your app runs in their terminal. No install on their side, no website, no mobile app. I use this internally to share tools with collaborators — instead of deploying a web app, I push to the SSH host and everyone gets the new version on their next connection.

Why the test count matters

TUIs have so many edge cases around input modes (raw vs. cooked, focus during prompt, terminal resize mid-input) that regressions creep in silently. The rule on TerminalTUI from day one was: every component gets a test suite before it ships. That's ~2,185 tests today. It's the reason I can refactor the render loop on a Friday afternoon and still cut a release on Monday.

Minimal dependencies

The whole runtime plus build step sits on esbuild and Node.js built-ins. No other runtime dependencies. For a CLI tool people install and use in seconds, a small install footprint is a feature.

What's next

• Plugin system so people can ship custom components as packages.
• Better perf on very wide terminals — I've seen frame drops above ~300 columns in one specific component.
• Multi-pane layouts similar to tmux.

If you've been waiting for someone to make the terminal feel like a modern UI framework, try it and file issues. I'm trying to build toward something that feels complete — not a toy — and the fastest way to get there is people using it in weird ways I didn't plan for. See also my other projects.

Key takeaways

• The terminal deserves a real UI framework, not another render loop.
• Spatial navigation, file-based routing, and built-in themes are the three things people don't realize they miss until they have them.
• SSH hosting turns a CLI into a product — zero-install is a killer distribution channel.

References

• npm — terminaltui package
• GitHub — OmarMusayev/terminaltui
• Awesome TUIs (rothgar) — landscape of terminal UI projects
• Background reading — Building Terminal Interfaces with Node.js