Imported from David-Li0406/meta-skill-evloving (skill-flow/data/skills-refined-36k/skillsmp/react-nextjs-validator/SKILL.md). Install upstream with npx skills add David-Li0406/meta-skill-evloving --skill react-nextjs-validator. Copyright stays with the author.

React & Next.js Best Practices Validator

Overview

Comprehensive validator for React 19+ and Next.js 15+ best practices. Use this skill to review code, suggest better hooks, optimize performance, and ensure modern patterns are followed.

Core principle: Prefer Server Components, extract logic to custom hooks, memoize intentionally (not everywhere), and let React Compiler handle optimizations when available.

External reference: For Vercel's detailed performance rules (45 rules in 8 categories), see the vercel-react-best-practices skill. That skill provides prioritized rules for: eliminating waterfalls (async-), bundle optimization (bundle-), server-side performance (server-), client-side fetching (client-), re-render optimization (rerender-), rendering performance (rendering-), JavaScript patterns (js-), and advanced patterns (advanced-).

When to Use

digraph when_to_use {
    "React/Next.js code?" [shape=diamond];
    "Choosing a hook?" [shape=diamond];
    "Performance issue?" [shape=diamond];
    "Component structure?" [shape=diamond];
    "Use this skill" [shape=box, style=filled, fillcolor=lightgreen];
    "Skip" [shape=box];

    "React/Next.js code?" -> "Use this skill" [label="yes"];
    "React/Next.js code?" -> "Skip" [label="no"];
    "Choosing a hook?" -> "Use this skill" [label="yes"];
    "Performance issue?" -> "Use this skill" [label="yes"];
    "Component structure?" -> "Use this skill" [label="yes"];
}

Use when:

Reviewing React component code
Choosing between hooks (useState vs useReducer, useMemo vs useCallback)
Optimizing re-renders or bundle size
Deciding Server vs Client Components
Extracting logic to custom hooks
Implementing forms with React 19 Actions

Skip when: Non-React code, simple HTML/CSS only

Quick Reference: Hook Selection

Situation	Use This	Not This
Simple primitive state	`useState`	`useReducer`
3+ related useState calls	`useReducer`	Multiple `useState`
Complex state transitions	`useReducer`	`useState` with objects
Expensive calculation	`useMemo`	Recalculate every render
Function passed to memoized child	`useCallback`	Inline function
Form submission state	`useFormStatus`	Manual `isLoading` state
Optimistic UI updates	`useOptimistic`	Manual optimistic state
Form action state	`useActionState`	`useState` + `useEffect`
Read promise in render	`use`	`useEffect` + `useState`
Side effect on mount/change	`useEffect`	Inline code
DOM measurement before paint	`useLayoutEffect`	`useEffect`
Share logic between components	Custom hook	Copy-paste code

React 19 New Hooks

useActionState

Replaces manual loading/error/success state management for actions.

// ❌ OLD: Manual state management
const [isLoading, setIsLoading] = useState(false);
const [error, setError] = useState(null);
const [data, setData] = useState(null);

const handleSubmit = async () => {
  setIsLoading(true);
  try {
    const result = await submitForm();
    setData(result);
  } catch (e) {
    setError(e);
  } finally {
    setIsLoading(false);
  }
};

// ✅ NEW: useActionState
const [state, submitAction, isPending] = useActionState(
  async (previousState, formData) => {
    const result = await submitForm(formData);
    return result;
  },
  initialState
);

useFormStatus

Access form submission state from any child component without prop drilling.

// ✅ Inside a form - no props needed
function SubmitButton() {
  const { pending, data, method, action } = useFormStatus();
  return (
    <button disabled={pending}>
      {pending ? 'Submitting...' : 'Submit'}
    </button>
  );
}

Rule: Must be used inside a <form> - won't work outside form context.

useOptimistic

Instant UI feedback before server response.

// ✅ Optimistic updates
function TodoList({ todos, addTodo }) {
  const [optimisticTodos, addOptimisticTodo] = useOptimistic(
    todos,
    (state, newTodo) => [...state, { ...newTodo, pending: true }]
  );

  const handleAdd = async (formData) => {
    const newTodo = { text: formData.get('text'), id: Date.now() };
    addOptimisticTodo(newTodo); // Instant UI update
    await addTodo(newTodo);     // Server request
  };

  return (
    <ul>
      {optimisticTodos.map(todo => (
        <li key={todo.id} style={{ opacity: todo.pending ? 0.5 : 1 }}>
          {todo.text}
        </li>
      ))}
    </ul>
  );
}

use API

Read promises and context conditionally in render.

// ✅ Read promise in render (with Suspense)
function UserProfile({ userPromise }) {
  const user = use(userPromise); // Suspends until resolved
  return <div>{user.name}</div>;
}

// ✅ Conditional context (not possible with useContext)
function Theme({ isAdmin }) {
  if (isAdmin) {
    const theme = use(AdminThemeContext);
    return <AdminPanel theme={theme} />;
  }
  return <UserPanel />;
}

Hooks: Do's and Don'ts

useState

✅ DO	❌ DON'T
Use for simple, independent values	Store derived state (calculate instead)
Use functional updates when depending on prev state	Mutate state directly
Initialize with function for expensive computations	Create objects/arrays inline in useState
Keep state close to where it's used	Lift state higher than necessary

// ❌ Derived state anti-pattern
const [items, setItems] = useState([]);
const [filteredItems, setFilteredItems] = useState([]); // Derived!

useEffect(() => {
  setFilteredItems(items.filter(i => i.active));
}, [items]);

// ✅ Calculate derived values
const [items, setItems] = useState([]);
const filteredItems = items.filter(i => i.active); // Calculated each render
// Or memoize if expensive:
const filteredItems = useMemo(() => items.filter(i => i.active), [items]);

useReducer

✅ DO	❌ DON'T
Use when 3+ related useState calls	Use for simple boolean toggles
Use when next state depends on previous	Mutate state in reducer
Group related state transitions	Create massive switch statements
Return new state object always	Forget to handle unknown actions

// ✅ Good useReducer pattern
type State = { status: 'idle' | 'loading' | 'success' | 'error'; data: Data | null; error: Error | null };
type Action =
  | { type: 'FETCH_START' }
  | { type: 'FETCH_SUCCESS'; payload: Data }
  | { type: 'FETCH_ERROR'; error: Error };

function reducer(state: State, action: Action): State {
  switch (action.type) {
    case 'FETCH_START':
      return { ...state, status: 'loading', error: null };
    case 'FETCH_SUCCESS':
      return { status: 'success', data: action.payload, error: null };
    case 'FETCH_ERROR':
      return { status: 'error', data: null, error: action.error };
    default:
      return state;
  }
}

useMemo & useCallback

✅ DO	❌ DON'T
Use when calculation is noticeably slow	Wrap everything "just in case"
Use when value is passed to memoized child	Use for simple calculations
Use when value is a useEffect dependency	Forget: initial render is slower with memo
Remove when React Compiler is active	Create new objects/arrays in dependencies

// ❌ Unnecessary memoization
const doubled = useMemo(() => count * 2, [count]); // Simple math

// ✅ Necessary memoization
const sortedItems = useMemo(() =>
  [...items].sort((a, b) => a.name.localeCompare(b.name)),
  [items]
); // Expensive for large arrays

// ✅ useCallback for memoized child
const handleClick = useCallback(() => {
  onItemSelect(item.id);
}, [item.id, onItemSelect]);

<MemoizedButton onClick={handleClick} /> // Won't re-render unnecessarily

React Compiler (2025): With React Compiler enabled, remove manual useMemo/useCallback - the compiler handles optimization automatically.

useEffect

✅ DO	❌ DON'T
Synchronize with external systems	Fetch data (use Server Components/TanStack Query)
Set up subscriptions/event listeners	Transform data for rendering
Always return cleanup function	Use async directly on useEffect
Keep dependency array accurate	Omit dependencies to "fix" infinite loops
Use one effect per concern	Put unrelated logic in same effect

// ❌ Common mistakes
useEffect(async () => { // Can't be async directly
  const data = await fetchData();
}, []);

useEffect(() => {
  fetchData(); // No cleanup for async
}, []);

// ✅ Correct patterns
useEffect(() => {
  let cancelled = false;

  async function fetchData() {
    const result = await api.getData();
    if (!cancelled) setData(result);
  }

  fetchData();
  return () => { cancelled = true; }; // Cleanup
}, []);

// ✅ Better: Use TanStack Query or Server Components instead

Dependency Array Rules:

Empty [] = run once on mount
No array = run every render (usually wrong)
[dep1, dep2] = run when deps change
State setters are stable - don't need to be in deps

Custom Hooks: When to Extract

Extract When

digraph extract_logic {
    "Logic in component" [shape=box];
    "Reused elsewhere?" [shape=diamond];
    "3+ primitive hooks?" [shape=diamond];
    "External system sync?" [shape=diamond];
    "Complex/hard to read?" [shape=diamond];
    "Extract to custom hook" [shape=box, style=filled, fillcolor=lightgreen];
    "Keep inline" [shape=box];

    "Logic in component" -> "Reused elsewhere?";
    "Reused elsewhere?" -> "Extract to custom hook" [label="yes"];
    "Reused elsewhere?" -> "3+ primitive hooks?" [label="no"];
    "3+ primitive hooks?" -> "Extract to custom hook" [label="yes"];
    "3+ primitive hooks?" -> "External system sync?" [label="no"];
    "External system sync?" -> "Extract to custom hook" [label="yes"];
    "External system sync?" -> "Complex/hard to read?" [label="no"];
    "Complex/hard to read?" -> "Extract to custom hook" [label="yes"];
    "Complex/hard to read?" -> "Keep inline" [label="no"];
}

Signs to Extract

Signal	Action
Same useState+useEffect combo in 2+ components	Extract to `useXxx` hook
3+ useState calls managing related state	Extract or use useReducer
useEffect syncing with external API/system	Extract to hide implementation
Can't name the hook clearly	Not ready to extract yet
Logic is component-specific, used once	Keep inline

// ❌ Repeated pattern across components
function ComponentA() {
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState(null);

  useEffect(() => {
    setLoading(true);
    fetchData().then(setData).catch(setError).finally(() => setLoading(false));
  }, []);
  // ...
}

// ✅ Extracted custom hook
function useData(fetchFn) {
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    let cancelled = false;
    fetchFn()
      .then(result => !cancelled && setData(result))
      .catch(err => !cancelled && setError(err))
      .finally(() => !cancelled && setLoading(false));
    return () => { cancelled = true; };
  }, [fetchFn]);

  return { data, loading, error };
}

// ✅ Even better: Use TanStack Query
const { data, isLoading, error } = useQuery({ queryKey: ['data'], queryFn: fetchData });

Custom Hook Rules

✅ DO	❌ DON'T
Name with `use` prefix	Return JSX from hooks
Return values/functions only	Call hooks conditionally inside
Make hooks composable	Couple to specific components
Document the contract	Hide too much (make debugging hard)

Performance Optimization

Re-render Prevention

Technique	When to Use	Impact
`React.memo`	Child re-renders with same props	Skip re-render
`useMemo`	Expensive calculation	Cache result
`useCallback`	Function passed to memo'd child	Stable reference
State colocation	State used by few components	Fewer re-renders
Context splitting	Context updates cause wide re-renders	Targeted updates

// ❌ Re-renders all children on any context change
const AppContext = createContext({ user: null, theme: 'light', notifications: [] });

// ✅ Split contexts by update frequency
const UserContext = createContext(null);      // Rarely changes
const ThemeContext = createContext('light');  // Rarely changes
const NotificationContext = createContext([]); // Frequently changes

List Virtualization

For lists with 100+ items, use virtualization:

import { useVirtualizer } from '@tanstack/react-virtual';

function VirtualList({ items }) {
  const parentRef = useRef(null);

  const virtualizer = useVirtualizer({
    count: items.length,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 50,
  });

  return (
    <div ref={parentRef} style={{ height: 400, overflow: 'auto' }}>
      <div style={{ height: virtualizer.getTotalSize() }}>
        {virtualizer.getVirtualItems().map(virtualItem => (
          <div
            key={virtualItem.key}
            style={{
              position: 'absolute',
              top: virtualItem.start,
              height: virtualItem.size,
            }}
          >
            {items[virtualItem.index].name}
          </div>
        ))}
      </div>
    </div>
  );
}

Code Splitting

// ✅ Route-based splitting
const Dashboard = lazy(() => import('./Dashboard'));
const Settings = lazy(() => import('./Settings'));

function App() {
  return (
    <Suspense fallback={<Loading />}>
      <Routes>
        <Route path="/dashboard" element={<Dashboard />} />
        <Route path="/settings" element={<Settings />} />
      </Routes>
    </Suspense>
  );
}

// ✅ Component-based splitting for heavy components
const HeavyChart = lazy(() => import('./HeavyChart'));

function Analytics() {
  return (
    <div>
      <h1>Analytics</h1>
      <Suspense fallback={<ChartSkeleton />}>
        <HeavyChart />
      </Suspense>
    </div>
  );
}

Next.js 15+ Best Practices

Server vs Client Components

digraph component_choice {
    "Need interactivity?" [shape=diamond];
    "Need browser APIs?" [shape=diamond];
    "Need React state/hooks?" [shape=diamond];
    "Server Component" [shape=box, style=filled, fillcolor=lightgreen];
    "Client Component" [shape=box, style=filled, fillcolor=lightyellow];

    "Need interactivity?" -> "Client Component" [label="yes"];
    "Need interactivity?" -> "Need browser APIs?" [label="no"];
    "Need browser APIs?" -> "Client Component" [label="yes"];
    "Need browser APIs?" -> "Need React state/hooks?" [label="no"];
    "Need React state/hooks?" -> "Client Component" [label="yes"];
    "Need React state/hooks?" -> "Server Component" [label="no"];
}

Server Components ✅	Client Components ✅
Data fetching	onClick, onChange, onSubmit
Backend resources access	useState, useReducer, useEffect
Sensitive data (API keys)	Browser APIs (localStorage, etc.)
Large dependencies	Custom hooks with state
Static content	Real-time updates

// ✅ Server Component (default) - fetches data
async function UserProfile({ userId }) {
  const user = await db.user.findUnique({ where: { id: userId } });
  return (
    <div>
      <h1>{user.name}</h1>
      <UserActions user={user} /> {/* Client island */}
    </div>
  );
}

// ✅ Client Component - handles interactivity
'use client';
function UserActions({ user }) {
  const [isFollowing, setIsFollowing] = useState(user.isFollowing);
  return (
    <button onClick={() => setIsFollowing(!isFollowing)}>
      {isFollowing ? 'Unfollow' : 'Follow'}
    </button>
  );
}

Pattern: Keep most UI as Server Components, isolate interactivity in small Client Component "islands".

Data Fetching Patterns

Pattern	Use Case
Server Component fetch	Initial data, SEO content
Server Actions	Mutations, form submissions
TanStack Query	Client-side caching, real-time
`use` + Suspense	Streaming dynamic data

// ✅ Server Component data fetching
async function ProductPage({ id }) {
  const product = await fetch(`/api/products/${id}`).then(r => r.json());
  return <ProductDetails product={product} />;
}

// ✅ Server Action for mutations
'use server';
async function updateProduct(formData: FormData) {
  const id = formData.get('id');
  const name = formData.get('name');
  await db.product.update({ where: { id }, data: { name } });
  revalidatePath(`/products/${id}`);
}

// ✅ Client with TanStack Query for real-time
'use client';
function LiveComments({ postId }) {
  const { data: comments } = useQuery({
    queryKey: ['comments', postId],
    queryFn: () => fetchComments(postId),
    refetchInterval: 5000,
  });
  return <CommentList comments={comments} />;
}

Caching in Next.js 15

Breaking change: Next.js 15 changed caching defaults - fetch requests are NOT cached by default.

Cache Type	Default (v15)	Control
fetch()	No cache	`cache: 'force-cache'`
Route segments	Dynamic	`export const dynamic = 'force-static'`
Router Cache	0 staleTime	Automatic for navigation

// ✅ Opt-in to caching
const data = await fetch(url, { cache: 'force-cache' }); // Cached
const data = await fetch(url, { next: { revalidate: 3600 } }); // ISR

// ✅ Route segment config
export const dynamic = 'force-static'; // SSG
export const revalidate = 60; // ISR every 60s

// ✅ Revalidate after mutation
'use server';
async function createPost(formData: FormData) {
  await db.post.create({ data: { title: formData.get('title') } });
  revalidatePath('/posts');
  revalidateTag('posts');
}

Next.js Performance Checklist

Area	Best Practice
Images	Use `next/image` with explicit width/height, `placeholder="blur"`
Fonts	Use `next/font`, limit weights, enable `display: swap`
Scripts	Use `next/script` with `lazyOnload` for third-party
Bundle	Analyze with `@next/bundle-analyzer`, use `optimizePackageImports`
Rendering	Default to Server Components, minimize Client Component scope
Streaming	Use Suspense boundaries for dynamic content
PPR	Enable Partial Prerendering for mixed static/dynamic routes

// ✅ Optimized Image
import Image from 'next/image';

<Image
  src="/hero.jpg"
  alt="Hero"
  width={1200}
  height={600}
  placeholder="blur"
  blurDataURL={blurUrl}
  priority // For above-fold images
/>

// ✅ Optimized Font
import { Inter } from 'next/font/google';

const inter = Inter({
  subsets: ['latin'],
  display: 'swap',
  variable: '--font-inter',
});

// ✅ Third-party Script
import Script from 'next/script';

<Script
  src="https://analytics.example.com/script.js"
  strategy="lazyOnload"
/>

Partial Prerendering (PPR)

Combines static shell with streamed dynamic content:

// next.config.js
module.exports = {
  experimental: {
    ppr: true,
  },
};

// Page with PPR
export default async function ProductPage({ params }) {
  const product = await getProduct(params.id); // Static at build

  return (
    <div>
      <h1>{product.name}</h1>
      <p>{product.description}</p>

      {/* Dynamic content streamed */}
      <Suspense fallback={<PriceSkeleton />}>
        <DynamicPrice productId={params.id} />
      </Suspense>

      <Suspense fallback={<ReviewsSkeleton />}>
        <DynamicReviews productId={params.id} />
      </Suspense>
    </div>
  );
}

Anti-Patterns to Avoid

Component Anti-Patterns

❌ Anti-Pattern	✅ Solution
Prop drilling through 3+ levels	Context, Zustand, or composition
Massive components (500+ lines)	Extract custom hooks, split components
Inline object/function props	Memoize with useMemo/useCallback
Storing derived state	Calculate or memoize instead
useEffect for data transformation	Transform during render
Index as key for dynamic lists	Use stable unique IDs

State Anti-Patterns

❌ Anti-Pattern	✅ Solution
Everything in global state	Keep local state local
Mutating state directly	Always create new references
Syncing state with useEffect	Single source of truth
Multiple useState for related data	useReducer
Context for frequently changing data	Zustand, Jotai, or split contexts

useEffect Anti-Patterns

❌ Anti-Pattern	✅ Solution
Missing cleanup function	Always return cleanup
Missing/wrong dependencies	Use exhaustive-deps lint rule
Async useEffect	Create inner async function
Data fetching in useEffect	Server Components, TanStack Query
Transforming props to state	useMemo or calculate inline

Code Review Checklist

When reviewing React/Next.js code, check:

Hooks

No hooks called conditionally or in loops
useEffect has accurate dependency array
useEffect has cleanup when needed
useMemo/useCallback used only when necessary
React 19 hooks used where applicable (useActionState, useOptimistic)
Custom hooks extracted for reused logic

Performance

React.memo used for expensive pure components
No inline objects/functions passed to memoized children
Large lists virtualized
Code split at route boundaries
No derived state stored in useState

Next.js

Server Components by default
'use client' only where needed
Images use next/image with dimensions
Fonts use next/font
Proper caching strategy configured
Server Actions for mutations

About

React & Next.js Best Practices Validator

Overview

When to Use

Quick Reference: Hook Selection

React 19 New Hooks

useActionState

useFormStatus

useOptimistic

use API

Hooks: Do's and Don'ts

useState

useReducer

useMemo & useCallback

useEffect

Custom Hooks: When to Extract

Extract When

Signs to Extract

Custom Hook Rules

Performance Optimization

Re-render Prevention

List Virtualization

Code Splitting

Next.js 15+ Best Practices

Server vs Client Components

Data Fetching Patterns

Caching in Next.js 15

Next.js Performance Checklist

Partial Prerendering (PPR)

Anti-Patterns to Avoid

Component Anti-Patterns

State Anti-Patterns

useEffect Anti-Patterns

Code Review Checklist

Hooks

Performance

Next.js

State

Sources

React 19

Hooks Best Practices

Performance

Custom Hooks

Next.js

Anti-Patterns

Use it

Manifest

Reviews