Skip to content

frontend-nextjs-example.md

Latest commit

 

History

History
223 lines (153 loc) · 7.63 KB

frontend-nextjs-example.md

File metadata and controls

223 lines (153 loc) · 7.63 KB
description DeSo Frontend Starter for NextJS and React apps

3️⃣ Frontend: NextJS Example

Primary Contributor & Maintainer: @brootle

A modern frontend web application built using Next.js App Router and designed to integrate with the DeSo Protocol — a decentralized social blockchain platform.

📦 Repository: brootle/deso-starter-nextjs-plus

This starter includes:

  • DeSo authentication via Identity service
  • Profile selector and alternate identity switching
  • Advanced commenting system with optimistic updates
  • Network-resilient data fetching and caching
  • Clean UI component system (Buttons, Inputs, Dropdowns, Select, etc.)
  • Support for Floating UI dropdowns and portals
  • Dark/light theming via CSS variables
  • Storybook for component exploration

🔥 Features

  • 🔐 DeSo Auth: Log in using DeSo Identity
  • 👥 Alt Profile Switcher: Switch between multiple public keys
  • 🔎 Search Profiles: Find users by public key or username
  • 📝 Post Support: Read and create posts on the DeSo blockchain
  • 💬 Advanced Comments: Inline replies with optimistic updates and smart caching
  • 🌐 Network Resilient: Handles offline/online transitions gracefully
  • 👻 Profileless Accounts: Fully functional even without a user profile
  • 🎨 Component Library: Custom Select, MenuItem, Avatar, and Dropdown components
  • 🌐 Responsive UI: Built with modular CSS and theme tokens
  • 📦 Floating UI: Precise positioning via @floating-ui/react
  • 🧱 Scalable Structure: Clean folder structure for extending easily

🧠 State Management with React Query

This starter uses TanStack React Query for efficient, declarative data fetching and caching with enterprise-grade reliability.

✅ Core Benefits:

  • Smart caching and deduplication of network requests
  • Declarative useQuery / useMutation hooks
  • Built-in error/loading states
  • React Query Devtools support (optional)

✅ Network Resilience Features:

  • Wake-from-sleep protection - No more "failed to fetch" errors when laptop wakes up
  • Smart retry logic - Won't retry when offline or for client errors
  • Progressive retry delays - Intelligent backoff (1s, 2s, 4s, 8s, max 15s)
  • Offline awareness - Graceful handling of network transitions
  • Centralized configuration - Consistent behavior across all pages

💬 Advanced Comment System

The commenting system features sophisticated state management and user experience optimizations:

✅ Real-time Features:

  • Optimistic updates - Comments appear instantly while syncing to blockchain
  • Local/remote merging - Seamlessly combines user's new comments with server data
  • Infinite pagination - Load more comments on demand
  • Smart deduplication - Prevents duplicate comments across page loads

✅ User Experience:

  • Inline replies - Reply directly from any post without page navigation
  • Expand/collapse - Show/hide comment threads with state persistence
  • Comment promotion - Local comments become permanent after server sync
  • Visual feedback - Clear loading states and error handling

Usage examples include:

  • Fetching user profiles by public key or username
  • Fetching posts and comments with infinite scroll
  • Creating replies with optimistic UI updates
  • Managing complex UI state like comment visibility
  • Handling username → public key resolution for notifications and feeds

Query keys are centralized in /queries/queryKeys.js, UI keys in /queries/uiKeys.js, and network configuration in /queries/queryClientConfig.js for consistency and maintainability.

🔧 Profile editing and mutations use invalidateQueries() for cache synchronization and support optimistic updates.

🚀 Getting Started

1. Clone the repository

git clone https://github.com/brootle/deso-starter-nextjs-plus.git
cd deso-starter-nextjs-plus

2. Install dependencies

npm install

3. Start the dev server

npm run dev

Visit http://localhost:3000 to view the app.

🧪 Storybook

Run Storybook to browse UI components in isolation:

npm run storybook

Opens at: http://localhost:6006

🛠 Tech Stack

  • Framework: Next.js App Router (v15.2.4)
  • UI Logic: React 19 + CSS Modules
  • Data Fetching & Caching: React Query v5 with network-aware configuration
  • State Management: React Context (Auth, User) + React Query for UI state
  • Floating Dropdowns: @floating-ui/react
  • DeSo Identity: Authentication via DeSo Identity service
  • Theming: CSS variable-based dark/light support

🧩 Folder Structure

/api               → DeSo API abstraction hooks and handlers
/app               → Next.js App Router structure (routes, pages, layout)
/assets            → Static assets like icons and illustrations
/components        → Reusable UI components (Button, Select, Input, etc.)
/config            → Environment-independent constants (e.g. API base URLs)
/context           → Global state via React Context API (Auth, User, QueryProvider)
/hooks             → Custom React hooks (e.g. useClickOutside, useToast)
/layouts           → Shared layout components (MainLayout, etc.)
/queries           → React Query configuration and key definitions
  ├── queryKeys.js         → API query keys
  ├── uiKeys.js           → UI state keys  
  ├── queryClientConfig.js → Network-aware configuration
  └── index.js            → Clean exports
/styles            → Theme system and shared styles (CSS Modules + variables)
/utils             → Helper functions (auth, DeSo profiles, tokens)

🔧 Query Configuration

The app features a sophisticated React Query setup optimized for reliability:

Network-Aware Retry Logic

// Won't retry when offline or for client errors (4xx)
// Uses progressive delays: 1s → 2s → 4s → 8s → max 15s
const networkAwareRetry = (failureCount, error) => {
  if (!navigator.onLine) return false;
  if (error?.status >= 400 && error?.status < 500) return false;
  return failureCount < 2;
};

Wake-from-Sleep Protection

// Prevents "failed to fetch" errors when laptop wakes up
refetchOnReconnect: false,  // Key setting
refetchOnWindowFocus: false,

Smart Cache Management

  • API queries: 2-minute stale time, 10-minute cache time
  • Search queries: 30-second stale time for fresh results
  • Comments: Infinite stale time for persistent threading
  • UI state: Cached for consistent user experience

📜 License

This project is open-sourced under the MIT License.

🤝 Contributing

Pull requests are welcome! Open issues or suggestions any time.

🌍 Credits

Built using the DeSo Protocol — the decentralized social blockchain.

🪲 Known Issues and Bug Reports

During development, several minor issues were identified with the DeSo backend API:

Open Issues

  • Unresolved: See this bug report for details on an issue that remains open.

Resolved Issues

  • Fixed: A previously reported bug has been addressed. Refer to this issue for more information.

If you encounter additional issues, please report them via the appropriate GitHub repository.