3๏ธโฃFrontend: NextJS Example
DeSo Frontend Starter for NextJS and React apps
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
hooksBuilt-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.
Last updated
Was this helpful?