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
- 🔐 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
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/useMutationhooks - 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
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.
git clone https://github.com/brootle/deso-starter-nextjs-plus.git
cd deso-starter-nextjs-plusnpm installnpm run devVisit http://localhost:3000 to view the app.
Run Storybook to browse UI components in isolation:
npm run storybookOpens at: http://localhost:6006
- 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
/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)
The app features a sophisticated React Query setup optimized for reliability:
// 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;
};// Prevents "failed to fetch" errors when laptop wakes up
refetchOnReconnect: false, // Key setting
refetchOnWindowFocus: false,- 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
This project is open-sourced under the MIT License.
Pull requests are welcome! Open issues or suggestions any time.
Built using the DeSo Protocol — the decentralized social blockchain.
During development, several minor issues were identified with the DeSo backend API:
- Unresolved: See this bug report for details on an issue that remains open.
- 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.