Skip to content

nickgallick/perlantir-fleet / workspace-forge/skills/react-nextjs

react-nextjs

Unverified

React & Next.js — Forge Skill

Overview

We use Next.js with the App Router. Understanding the server/client boundary is the most critical aspect of reviewing React code in this project.

Server/Client Boundary

The Rule

Components are Server Components by default in the App Router. They only become Client Components when marked with 'use client'.

When 'use client' Is Required

  • Using hooks (useState, useEffect, useContext, etc.)
  • Using browser APIs (window, document, localStorage)
  • Adding event handlers (onClick, onChange, etc.)
  • Using useRouter() from next/navigation for programmatic navigation
  • Using third-party libraries that use any of the above

When 'use client' Should NOT Be Used

  • Components that only render data (no interactivity)
  • Components that fetch data from the database
  • Layout components that just compose children
  • Components that only use server-side imports

Common Mistakes

// BAD — entire page is a client component because of one click handler
'use client';

export default function ProductPage({ params }: Props) {
  const product = await fetchProduct(params.id); // Can't await in client!
  return (
    <div>
      <h1>{product.name}</h1>
      <AddToCartButton productId={product.id} />
    </div>
  );
}

// GOOD — server component with client island
export default async function ProductPage({ params }: Props) {
  const product = await fetchProduct(params.id);
  return (
    <div>
      <h1>{product.name}</h1>
      <AddToCartButton productId={product.id} /> {/* This is 'use client' */}
    </div>
  );
}

Data Fetching

Server Components (Preferred)

// Direct database/API calls in Server Components
export default async function UsersPage() {
  const users = await getUsers(); // Direct call, no useEffect
  return <UserList users={users} />;
}

Server Actions

// app/actions.ts
'use server';

export async function createPost(formData: FormData) {
  const title = formData.get('title');
  // Validate with Zod
  // Write to database
  // Revalidate cache
  revalidatePath('/posts');
}

Client-Side Fetching (When Needed)

  • Use for real-time data, user-specific data after initial load, or infinite scroll
  • Use SWR or React Query for client-side data fetching — not raw useEffect + fetch
  • Always handle loading, error, and empty states

Anti-Pattern: Fetching in useEffect

// BAD — fetch in useEffect (waterfall, no cache, no error handling)
useEffect(() => {
  fetch('/api/users').then(r => r.json()).then(setUsers);
}, []);

// GOOD — use the data fetching library
const { data, error, isLoading } = useSWR('/api/users', fetcher);

Component Architecture

Composition Over Props Drilling

// BAD — prop drilling
<App user={user}>
  <Layout user={user}>
    <Sidebar user={user}>
      <UserAvatar user={user} />

// GOOD — composition
<App>
  <Layout sidebar={<Sidebar><UserAvatar user={user} /></Sidebar>}>
    {children}
  </Layout>
</App>

Component Size

  • Components should do ONE thing
  • If a component file exceeds ~150 lines, consider splitting
  • Extract custom hooks for complex logic
  • Keep render logic readable

File Organization

app/
  (auth)/
    login/page.tsx
    register/page.tsx
  (dashboard)/
    layout.tsx
    page.tsx
  api/
    users/route.ts
components/
  ui/           # Generic, reusable (Button, Input, Modal)
  features/     # Feature-specific (UserProfile, PostEditor)
hooks/
  useAuth.ts
  useDebounce.ts
lib/
  supabase/
    client.ts
    server.ts
  utils.ts

State Management

Decision Tree

  1. Server state → Fetch in Server Components (preferred)
  2. URL state → Use searchParams, useSearchParams()
  3. Form state → Use useActionState() or React Hook Form
  4. Local UI state → useState (toggle, modal open, etc.)
  5. Shared client state → React Context (small), Zustand (complex)
  6. Real-time state → Supabase Realtime subscriptions

Anti-Pattern: Global State for Server Data

// BAD — putting server data in Zustand
const useStore = create((set) => ({
  users: [],
  fetchUsers: async () => {
    const users = await fetch('/api/users').then(r => r.json());
    set({ users });
  },
}));

// GOOD — fetch in Server Component, or use SWR/React Query for client

Anti-Patterns to Flag

PatternIssueFix
'use client' on a page that fetches dataLoses server rendering benefitsSplit into server page + client islands
useEffect for data fetchingNo caching, waterfalls, race conditionsUse Server Components or SWR/React Query
Prop drilling more than 2-3 levelsHard to maintain, brittleUse composition, context, or restructure
Importing server-only code in client componentsBuild error or security riskCheck import boundaries
Using router.push() instead of <Link>Loses prefetchingUse <Link> for navigation
key={index} on dynamic listsIncorrect reconciliationUse stable unique IDs
Large 'use client' componentsIncreases client bundleExtract server parts out
Missing loading.tsx or error.tsxNo loading/error UI for the routeAdd route-level loading and error boundaries
Direct DOM manipulation in ReactBypasses React's reconciliationUse refs and React patterns

Review Severity

IssueSeverity
Server-only code exposed to clientP0 — BLOCKED
Missing error boundary on critical routesP1 — High
Unnecessary 'use client' on data-fetching pageP1 — High
Data fetching in useEffect without good reasonP2 — Medium
Missing loading statesP2 — Medium
Prop drilling (3+ levels)P3 — Low
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 192kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 192kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 192kUpdated Claude CodeCodexVerifiedInstall