HackerNews TUI

Description

An interactive terminal user interface (TUI) for browsing HackerNews. Built with Rust to provide a fast, keyboard-driven experience for reading HN stories and comments.

Screenshots

Installation

From Source

cargo install --path .

Then run with:

hn

Running Directly

cargo run --release

Features

Stories View

• Browse Stories: View top, new, or best stories from HackerNews
• Keyboard Navigation: Navigate with vim-style keys (j/k) or arrow keys
• Pagination: Move between pages of stories
• Quick Story Type Switching: Press 1/2/3 to switch between Top/New/Best
• Open in Browser: Press 'o' or Enter to open story URL in your default browser
• View Comments: Press 'c' to view story comments

Comments View

• Nested Comments: View comment threads with unlimited nesting depth
• Lazy Loading: Comments and replies are loaded on-demand for faster initial load
• Expand/Collapse: Press Enter or l (or →) to expand or collapse comment replies
• Smooth Navigation: Navigate through comments with j/k keys; collapse a whole thread with c
• Jump to Top/Bottom: Press 'g' for top, 'G' for bottom
• Skip Threads: Jump to the next sibling thread with ] or previous sibling with [
• Climb Threads: Jump to the parent comment with u
• Thread Guides: Tree lines with depth-based colors to follow nested conversations at a glance

General

• Gentle Loading: Cached pages show instantly, lists stay visible/dim while updates stream in
• Asynchronous Loading: Non-blocking API requests with loading indicators
• Error Handling: Graceful error messages with retry options
• Help System: Press '?' for keyboard shortcuts
• Clean UI: Inherits your terminal colors for a native look

Keyboard Shortcuts

Stories View

Key	Action
j / ↓	Next story
k / ↑	Previous story
n / →	Next page
p / ←	Previous page
1	View Top stories
2	View New stories
3	View Best stories
Enter / o	Open story URL in browser
c	View comments
r	Refresh current page
?	Toggle help
q	Quit

Comments View

Key	Action
j / ↓	Next comment
k / ↑	Previous comment
]	Next sibling thread
[	Previous sibling thread
u	Jump to parent
g	Go to top
G	Go to bottom
Enter / l / →	Expand/collapse replies
c	Collapse current thread
o	Open story URL in browser
Esc / q / h / ←	Back to stories
?	Toggle help

Architecture

Built with:

• ratatui: Modern terminal UI framework
• crossterm: Cross-platform terminal manipulation
• tokio: Async runtime for non-blocking API requests
• reqwest: HTTP client for HackerNews API

Development

Build

cargo build

Run Tests

cargo test

Build for Release

cargo build --release

Project Structure

src/
├── main.rs          # Entry point, event loop
├── lib.rs           # Core service and data types
├── app.rs           # Application state management
├── event.rs         # Keyboard event handling
├── hn_client.rs     # HackerNews API client
├── time_utils.rs    # Time formatting utilities
└── ui/
    ├── mod.rs       # UI module exports
    ├── stories.rs   # Stories list rendering
    ├── comments.rs  # Comments tree rendering
    └── widgets.rs   # Reusable UI components

License

This project was created as a learning exercise to explore Rust and terminal UI development.