State Management

This document explains the state management approach used in the Rhesis frontend application.

State Management Architecture

The Rhesis frontend uses a hybrid state management approach:

Server Components: Data fetching and state management on the server
React Context: For global UI state and shared state across components
Local Component State: For component-specific state
Server Actions: For mutations and form submissions
URL State: For preserving state in the URL (e.g., filters, pagination)

This approach minimizes client-side state management while leveraging Next.js App Router features.

Server Components

Server components handle data fetching and initial state:


// app/(protected)/projects/page.tsx
import { projectsApi } from '@/utils/api-client/endpoints/projects';
import ProjectList from '@/components/projects/ProjectList';
 
export default async function ProjectsPage({
  searchParams,
}: {
  searchParams: { page?: string; limit?: string; search?: string };
}) {
  // Parse query parameters
  const page = parseInt(searchParams.page || '1', 10);
  const limit = parseInt(searchParams.limit || '10', 10);
  const search = searchParams.search || '';
 
  // Fetch data on the server
  const { data: projects, total } = await projectsApi.getAll({
    skip: (page - 1) * limit,
    limit,
    search,
  });
 
  return (
    <div>
      <h1>Projects ({total})</h1>
      <ProjectList
        projects={projects}
        total={total}
        page={page}
        limit={limit}
        search={search}
      />
    </div>
  );
}

React Context

For global state, the application uses React Context:

Context Definition


// src/components/providers/ThemeProvider.tsx
'use client';
 
import { createContext, useContext, useState, useEffect } from 'react';
 
type Theme = 'light' | 'dark' | 'system';
 
interface ThemeContextType {
  theme: Theme;
  setTheme: (theme: Theme) => void;
}
 
const ThemeContext = createContext<ThemeContextType | undefined>(undefined);
 
export function ThemeProvider({ children }: { children: React.ReactNode }) {
  const [theme, setTheme] = useState<Theme>('system');
 
  // Initialize theme from localStorage
  useEffect(() => {
    const savedTheme = localStorage.getItem('theme') as Theme | null;
    if (savedTheme) {
      setTheme(savedTheme);
    }
  }, []);
 
  // Update localStorage when theme changes
  useEffect(() => {
    localStorage.setItem('theme', theme);
 
    // Apply theme to document
    const isDark =
      theme === 'dark' ||
      (theme === 'system' && window.matchMedia('(prefers-color-scheme: dark)').matches);
 
    document.documentElement.classList.toggle('dark', isDark);
  }, [theme]);
 
  return (
    <ThemeContext.Provider value={{ theme, setTheme }}>
      {children}
    </ThemeContext.Provider>
  );
}
 
export function useTheme() {
  const context = useContext(ThemeContext);
  if (context === undefined) {
    throw new Error('useTheme must be used within a ThemeProvider');
  }
  return context;
}

Context Usage


// src/components/layout/ThemeToggle.tsx
'use client';
 
import { useTheme } from '@/components/providers/ThemeProvider';
 
export default function ThemeToggle() {
  const { theme, setTheme } = useTheme();
 
  const toggleTheme = () => {
    if (theme === 'light') {
      setTheme('dark');
    } else if (theme === 'dark') {
      setTheme('system');
    } else {
      setTheme('light');
    }
  };
 
  return (
    <button onClick={toggleTheme}>
      {theme === 'light' && 'Light Mode'}
      {theme === 'dark' && 'Dark Mode'}
      {theme === 'system' && 'System Theme'}
    </button>
  );
}

Context Setup


// app/layout.tsx
import { ThemeProvider } from '@/components/providers/ThemeProvider';
 
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <ThemeProvider>{children}</ThemeProvider>
      </body>
    </html>
  );
}

Local Component State

For component-specific state, use React’s built-in hooks:


// src/components/projects/ProjectFilter.tsx
'use client';
 
import { useState } from 'react';
import { useRouter, usePathname } from 'next/navigation';
 
export default function ProjectFilter({
  initialSearch = '',
}: {
  initialSearch?: string;
}) {
  const [search, setSearch] = useState(initialSearch);
  const router = useRouter();
  const pathname = usePathname();
 
  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
 
    // Update URL with search parameter
    const params = new URLSearchParams();
    if (search) {
      params.set('search', search);
    }
 
    router.push(`${pathname}?${params.toString()}`);
  };
 
  return (
    <form onSubmit={handleSubmit}>
      <input
        type="text"
        value={search}
        onChange={(e) => setSearch(e.target.value)}
        placeholder="Search projects..."
      />
      <button type="submit">Search</button>
    </form>
  );
}

Server Actions

For mutations and form submissions, use server actions:


// app/(protected)/projects/actions.ts
'use server';
 
import { revalidatePath } from 'next/cache';
import { projectsApi } from '@/utils/api-client/endpoints/projects';
import type { ProjectCreate } from '@/utils/api-client/types/projects';
 
export async function createProject(formData: FormData) {
  const name = formData.get('name') as string;
  const description = formData.get('description') as string;
 
  if (!name) {
    return { success: false, error: 'Name is required' };
  }
 
  try {
    await projectsApi.create({
      name,
      description: description || undefined,
    });
 
    revalidatePath('/projects');
    return { success: true };
  } catch (error) {
    return {
      success: false,
      error: error instanceof Error ? error.message : 'Failed to create project'
    };
  }
}

Using server actions in a form:


// src/components/projects/ProjectForm.tsx
'use client';
 
import { useFormState } from 'react-dom';
import { createProject } from '@/app/(protected)/projects/actions';
 
const initialState = { success: false, error: null };
 
export default function ProjectForm() {
  const [state, formAction] = useFormState(createProject, initialState);
 
  return (
    <form action={formAction}>
      <div>
        <label htmlFor="name">Name</label>
        <input id="name" name="name" required />
      </div>
 
      <div>
        <label htmlFor="description">Description</label>
        <textarea id="description" name="description" />
      </div>
 
      {state.error && <div className="error">{state.error}</div>}
 
      <button type="submit">Create Project</button>
    </form>
  );
}

URL State

For preserving state in the URL:


// src/components/common/Pagination.tsx
'use client';
 
import Link from 'next/link';
import { usePathname, useSearchParams } from 'next/navigation';
 
interface PaginationProps {
  total: number;
  page: number;
  limit: number;
}
 
export default function Pagination({ total, page, limit }: PaginationProps) {
  const pathname = usePathname();
  const searchParams = useSearchParams();
 
  const totalPages = Math.ceil(total / limit);
 
  const createPageURL = (pageNumber: number) => {
    const params = new URLSearchParams(searchParams);
    params.set('page', pageNumber.toString());
    return `${pathname}?${params.toString()}`;
  };
 
  return (
    <div className="pagination">
      {page > 1 && (
        <Link href={createPageURL(page - 1)}>Previous</Link>
      )}
 
      {Array.from({ length: totalPages }, (_, i) => i + 1).map((pageNumber) => (
        <Link
          key={pageNumber}
          href={createPageURL(pageNumber)}
          className={pageNumber === page ? 'active' : ''}
        >
          {pageNumber}
        </Link>
      ))}
 
      {page < totalPages && (
        <Link href={createPageURL(page + 1)}>Next</Link>
      )}
    </div>
  );
}

State Management Best Practices

Minimize Client-Side State: Use server components for data fetching where possible
Colocate State: Keep state as close as possible to where it’s used
Use URL for Shareable State: Store filters, pagination, and other shareable state in the URL
Prefer Server Actions: Use server actions for mutations instead of client-side API calls
Context for Global State: Use React Context for truly global state like theme, user preferences
Avoid Prop Drilling: Use context or composition to avoid excessive prop drilling
Revalidate After Mutations: Use revalidatePath to refresh data after mutations

Example: Complex State Management

For complex state management needs, combine these approaches:


// app/(protected)/projects/[id]/page.tsx
import { projectsApi } from '@/utils/api-client/endpoints/projects';
import ProjectDetails from '@/components/projects/ProjectDetails';
import { notFound } from 'next/navigation';
 
export default async function ProjectPage({
  params,
}: {
  params: { id: string };
}) {
  try {
    // Fetch data on the server
    const project = await projectsApi.getById(params.id);
 
    return <ProjectDetails project={project} />;
  } catch (error) {
    // Handle 404 errors
    notFound();
  }
}


// src/components/projects/ProjectDetails.tsx
'use client';
 
import { useState } from 'react';
import { useRouter } from 'next/navigation';
import { updateProject, deleteProject } from '@/app/(protected)/projects/actions';
import type { Project } from '@/utils/api-client/types/projects';
 
export default function ProjectDetails({ project }: { project: Project }) {
  const [isEditing, setIsEditing] = useState(false);
  const [name, setName] = useState(project.name);
  const [description, setDescription] = useState(project.description);
  const [error, setError] = useState<string | null>(null);
  const [isDeleting, setIsDeleting] = useState(false);
  const router = useRouter();
 
  const handleUpdate = async (e: React.FormEvent) => {
    e.preventDefault();
    setError(null);
 
    const result = await updateProject(project.id, {
      name,
      description,
    });
 
    if (result.success) {
      setIsEditing(false);
    } else {
      setError(result.error);
    }
  };
 
  const handleDelete = async () => {
    if (!window.confirm('Are you sure you want to delete this project?')) {
      return;
    }
 
    setIsDeleting(true);
    const result = await deleteProject(project.id);
 
    if (result.success) {
      router.push('/projects');
    } else {
      setError(result.error);
      setIsDeleting(false);
    }
  };
 
  if (isEditing) {
    return (
      <form onSubmit={handleUpdate}>
        {/* Edit form fields */}
        {error && <div className="error">{error}</div>}
        <div className="actions">
          <button type="submit">Save</button>
          <button type="button" onClick={() => setIsEditing(false)}>
            Cancel
          </button>
        </div>
      </form>
    );
  }
 
  return (
    <div>
      <h1>{project.name}</h1>
      <p>{project.description}</p>
      <div className="actions">
        <button onClick={() => setIsEditing(true)}>Edit</button>
        <button
          onClick={handleDelete}
          disabled={isDeleting}
        >
          {isDeleting ? 'Deleting...' : 'Delete'}
        </button>
      </div>
      {error && <div className="error">{error}</div>}
    </div>
  );
}