DevEx Developer Experience TUI Best Practices

Comprehensive developer experience guide for building TypeScript terminal user interfaces using Ink (React for CLIs) and Clack prompts. Contains 42 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

When to Apply

Reference these guidelines when:

• Building CLI tools with interactive prompts using @clack/prompts

• Creating React-based terminal UIs with Ink

• Handling keyboard input and user interactions

• Optimizing terminal rendering and preventing flicker

• Designing developer-friendly CLI experiences

Rule Categories by Priority

Priority Category Impact Prefix

1 Rendering & Output CRITICAL render-

2 Input & Keyboard CRITICAL input-

3 Component Patterns HIGH tuicomp-

4 State & Lifecycle HIGH tuistate-

5 Prompt Design MEDIUM-HIGH prompt-

6 UX & Feedback MEDIUM ux-

7 Configuration & CLI MEDIUM tuicfg-

8 Robustness & Compatibility LOW-MEDIUM robust-

Quick Reference

1. Rendering & Output (CRITICAL)

• render-single-write

• Batch Terminal Output in Single Write

• render-overwrite-dont-clear

• Overwrite Content Instead of Clear and Redraw

• render-synchronized-output

• Use Synchronized Output Protocol for Animations

• render-60fps-baseline

• Target 60fps for Smooth Animation

• render-partial-updates

• Update Only Changed Regions

• render-escape-sequence-batching

• Defer ANSI Escape Code Generation to Final Output

2. Input & Keyboard (CRITICAL)

• input-useinput-hook

• Use useInput Hook for Keyboard Handling

• input-immediate-feedback

• Provide Immediate Visual Feedback for Input

• input-modifier-keys

• Handle Modifier Keys Correctly

• input-isactive-focus

• Use isActive Option for Focus Management

• input-escape-routes

• Always Provide Escape Routes

3. Component Patterns (HIGH)

• tuicomp-box-flexbox

• Use Box Component with Flexbox for Layouts

• tuicomp-text-styling

• Use Text Component for All Visible Content

• tuicomp-measure-element

• Use measureElement for Dynamic Sizing

• tuicomp-static-for-logs

• Use Static Component for Log Output

• tuicomp-percentage-widths

• Use Percentage Widths for Responsive Layouts

• tuicomp-border-styles

• Use Border Styles for Visual Structure

4. State & Lifecycle (HIGH)

• tuistate-useapp-exit

• Use useApp Hook for Application Lifecycle

• tuistate-cleanup-effects

• Always Clean Up Effects on Unmount

• tuistate-functional-updates

• Use Functional State Updates to Avoid Stale Closures

• tuistate-usecallback-stable

• Stabilize Callbacks with useCallback

• tuistate-usememo-expensive

• Memoize Expensive Computations with useMemo

5. Prompt Design (MEDIUM-HIGH)

• prompt-group-flow

• Use Clack group() for Multi-Step Prompts

• prompt-validation

• Validate Input Early with Descriptive Messages

• prompt-cancellation

• Handle Cancellation Gracefully with isCancel

• prompt-spinner-tasks

• Use Spinner and Tasks for Long Operations

• prompt-custom-render

• Build Custom Prompts with @clack/core

6. UX & Feedback (MEDIUM)

• ux-progress-indicators

• Show Progress for Operations Over 1 Second

• ux-color-semantics

• Use Colors Semantically and Consistently

• ux-error-messages

• Write Actionable Error Messages

• ux-next-steps

• Show Next Steps After Completion

• ux-intro-outro

• Use Intro and Outro for Session Framing

7. Configuration & CLI (MEDIUM)

• tuicfg-sensible-defaults

• Provide Sensible Defaults for All Options

• tuicfg-env-vars

• Support Standard Environment Variables

• tuicfg-flags-over-args

• Prefer Flags Over Positional Arguments

• tuicfg-help-system

• Implement Comprehensive Help System

• tuicfg-json-output

• Support Machine-Readable Output Format

8. Robustness & Compatibility (LOW-MEDIUM)

• robust-tty-detection

• Detect TTY and Adjust Behavior Accordingly

• robust-signal-handling

• Handle Process Signals Gracefully

• robust-exit-codes

• Use Meaningful Exit Codes

• robust-terminal-restore

• Always Restore Terminal State on Exit

• robust-graceful-degradation

• Degrade Gracefully for Limited Terminals

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions - Category structure and impact levels

• Rule template - Template for adding new rules

• render-single-write - Example rule file

• input-useinput-hook - Example rule file

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md