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?