Debug OpenTUI applications using file-based logging when console.log is captured by the TUI overlay.
File-based debugging for OpenTUI apps since console.log output is captured by the TUI's debug overlay.
Log from components:
import { logDebug } from "./utils/debug.ts";
logDebug("render", { width, height, scrollOffset });
Agent reads the log:
read /path/to/project/debug.log
Use when:
console.log doesn't appear in terminal (captured by OpenTUI)src/utils/debug.ts - Logger utilitydebug.log - Output file (project root, gitignored)logDebug(label: string, data: unknown): void
Logs are appended with timestamps:
[2026-02-06T04:35:04.309Z] label:
{
"key": "value"
}
useEffectuseKeyboard handlersuseKeyboard((key) => {
logDebug("key", { name: key.name, mode: currentMode });
// ... handle
});
useEffect(() => {
logDebug("scroll", { offset, maxScroll, visible: rows.length });
}, [offset]);
| Issue | Fix |
|---|---|
| No log file | Restart app after adding logDebug() |
| Log not updating | Check logDebug() is actually called |
| Too verbose | Remove logs from frequently-rendered components |