Improve frontend developer experience and usability

[johnsmccain]

Summary

This PR implements lightweight frontend developer-experience and usability improvements across the Next.js application, including automated pre-commit quality checks, non-blocking health indicators, enhanced documentation, and improved Transaction Explorer filtering.

Changes Made

1. Automated Pre-commit Quality Checks

• Added husky and lint-staged for automated quality checks on staged files
• Configured lint-staged to run ESLint with auto-fix and Prettier on TypeScript/JavaScript files
• Created .husky/pre-commit hook that runs npx lint-staged before each commit
• Added PRE_COMMIT_HOOKS.md documentation with:
  • Setup instructions
  • Configuration details
  • Troubleshooting guide
  • Benefits of automated checks
• Updated package.json with lint-staged configuration for staged file processing

Benefits:

• Reduces CI churn by catching issues locally
• Ensures consistent code style across the codebase
• Provides immediate feedback during development
• Actionable error messages guide developers to fix issues

2. Non-blocking Network and Service Health Indicators

• Created useHealthStatus.ts hook with:
  • Cached status fetching (1-minute cache duration)
  • Neutral fallback states for unknown conditions
  • Non-blocking error handling that never interrupts workflows
  • Periodic refresh every 30 seconds
• Created HealthIndicator.tsx component that:
  • Displays chain health and API status in a compact, non-intrusive manner
  • Shows status icons with color-coded indicators (healthy/degraded/unhealthy/unknown)
  • Includes a refresh button on hover
  • Never interrupts core workflows
• Integrated HealthIndicator into Navbar (visible on large screens)

Design Decisions:

• Health indicators are non-blocking and don't interrupt user workflows
• Neutral fallback states ensure the UI remains functional even when health checks fail
• Cached fetching reduces unnecessary API calls
• Compact display in navbar maintains existing UI patterns

3. Enhanced Onboarding Documentation

• Enhanced Getting Started section with troubleshooting for:
  • Dependency installation (ENOSPC errors, cache clearing)
  • Environment setup (gitignore, variable loading, case sensitivity)
  • Development server (port conflicts, module not found, TypeScript errors)
  • Production build (TypeScript errors, memory issues, static assets)
• Expanded Scripts section with:
  • Additional commands (format:check, type-check)
  • Common workflows for pre-commit verification
• Updated pre-commit hooks section to reference the detailed documentation
• Comprehensive Troubleshooting section covering:
  • Module not found errors
  • TypeScript errors
  • Wallet connection issues
  • Pre-commit hook failures
  • Build failures
  • Environment variables not loading
  • Port already in use

Benefits:

• Clearer setup process for new developers
• Reduced onboarding time
• Self-service troubleshooting for common issues
• Better developer experience

4. Transaction Explorer Filtering Enhancement

• Enhanced empty-state messaging in TransactionFeed.tsx to:
  • Clearly indicate when no transactions match the current filters
  • Display active filters (search, status, chain, asset, range) when filters are applied
  • Provide context-aware messaging based on whether filters are active
  • Show the "Clear all filters" button only when filters are active
• Preserved existing UI patterns and application flow
• Maintained existing chain and status filtering functionality (already implemented)

Design Decisions:

• No redesign work - only enhanced messaging
• Preserved existing filtering UI patterns
• Context-aware messaging improves user understanding
• Clear guidance on how to reset filters

Files Changed

Modified

• frontend/README.md - Enhanced documentation with troubleshooting notes
• frontend/package.json - Added lint-staged configuration and dependencies
• frontend/package-lock.json - Updated dependencies
• frontend/src/components/layout/Navbar.tsx - Integrated HealthIndicator
• frontend/src/components/transactions/TransactionFeed.tsx - Enhanced empty-state messaging

Added

• frontend/.husky/pre-commit - Pre-commit hook for automated quality checks
• frontend/PRE_COMMIT_HOOKS.md - Documentation for pre-commit hooks
• frontend/src/components/ui/HealthIndicator.tsx - Non-blocking health indicator component
• frontend/src/hooks/useHealthStatus.ts - Hook for fetching health status with caching

Testing

Pre-commit Hooks

• Verified that husky and lint-staged are properly configured
• Confirmed that the pre-commit hook runs on staged files
• Tested that ESLint and Prettier are applied correctly

Health Indicators

• Verified that the useHealthStatus hook fetches and caches status
• Confirmed that the HealthIndicator component displays correctly
• Tested that health indicators don't interrupt core workflows
• Verified neutral fallback states for unknown conditions

Documentation

• Reviewed all added troubleshooting sections for accuracy
• Verified that commands are correct and executable
• Confirmed that documentation is clear and actionable

Transaction Explorer

• Tested empty-state messaging with various filter combinations
• Verified that active filters are displayed correctly
• Confirmed that "Clear all filters" button appears only when appropriate
• Tested that existing filtering functionality remains intact

Breaking Changes

None. All changes are additive and maintain backward compatibility.

Dependencies Added

• husky@^9.1.7 - Git hooks management
• lint-staged@^16.4.0 - Run linters on staged files

Related Issues

This PR addresses the request for lightweight frontend developer-experience and usability improvements.

Linked Issues

• Close [Frontend] Add Husky + lint-staged pre-commit checks #279
• Close [Frontend] Add network health status widget #287
• Close [Frontend] Add frontend onboarding script and README section #285
• Close [Frontend UX] Add transaction feed filter controls #414

[drips-wave]

@johnsmccain Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits