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 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

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?