react-best-practices
π―Skillfrom dedalus-erp-pas/foundation-skills
|Guides developers in writing high-performance, modern React and Next.js applications by providing best practices for component architecture, performance, and UI design.
Part of
dedalus-erp-pas/foundation-skills(21 items)
Installation
npx shadcn@latest add buttonnpx shadcn@latest add cardnpx shadcn@latest add dialognpx shadcn@latest add formnpm install motionSkill Details
Comprehensive React and Next.js best practices guide covering performance optimization, component architecture, shadcn/ui patterns, Motion animations, and modern React 19+ patterns. This skill should be used when writing, reviewing, or refactoring React/Next.js code. Triggers on tasks involving React components, Next.js pages, data fetching, UI components, animations, or code quality improvements.
Overview
# React Best Practices
Comprehensive guide for building modern React and Next.js applications. Covers performance optimization, component architecture, shadcn/ui patterns, Motion animations, accessibility, and React 19+ features.
When to Apply
Reference these guidelines when:
- Writing new React components or Next.js pages
- Implementing data fetching (client or server-side)
- Building UI with shadcn/ui components
- Adding animations and micro-interactions
- Reviewing code for quality and performance
- Refactoring existing React/Next.js code
- Optimizing bundle size or load times
Rule Categories by Priority
| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Component Architecture | CRITICAL | arch- |
| 2 | Eliminating Waterfalls | CRITICAL | async- |
| 3 | Bundle Size Optimization | CRITICAL | bundle- |
| 4 | Server Components & Actions | HIGH | server- |
| 5 | shadcn/ui Patterns | HIGH | shadcn- |
| 6 | State Management | MEDIUM-HIGH | state- |
| 7 | Motion & Animations | MEDIUM | motion- |
| 8 | Re-render Optimization | MEDIUM | rerender- |
| 9 | Accessibility | MEDIUM | a11y- |
| 10 | TypeScript Patterns | MEDIUM | ts- |
---
1. Component Architecture (CRITICAL)
Quick Reference
arch-functional-components- Use functional components with hooks exclusivelyarch-composition-over-inheritance- Build on existing components, don't extendarch-single-responsibility- Each component should do one thing wellarch-presentational-container- Separate UI from logic when beneficialarch-colocation- Keep related files together (component, styles, tests)arch-avoid-prop-drilling- Use Context or composition for deep props
Key Principles
Functional Components Only
```typescript
// Correct: Functional component with hooks
function UserProfile({ userId }: { userId: string }) {
const { data: user } = useUser(userId)
return
}
// Incorrect: Class component
class UserProfile extends React.Component { / ... / }
```
Composition Pattern
```typescript
// Correct: Compose smaller components
function Card({ children }: { children: React.ReactNode }) {
return
}
function CardHeader({ children }: { children: React.ReactNode }) {
return
}
// Usage
Content
```
Avoid Prop Drilling
```typescript
// Incorrect: Passing props through many levels
// Correct: Use Context for shared state
const UserContext = createContext
function App() {
const user = useCurrentUser()
return (
)
}
```
---
2. Eliminating Waterfalls (CRITICAL)
Quick Reference
async-defer-await- Move await into branches where actually usedasync-parallel- Use Promise.all() for independent operationsasync-dependencies- Handle partial dependencies correctlyasync-api-routes- Start promises early, await late in API routesasync-suspense-boundaries- Use Suspense to stream content
Key Principles
Waterfalls are the #1 performance killer. Each sequential await adds full network latency.
Parallel Data Fetching
```typescript
// Incorrect: Sequential waterfalls
async function Page() {
const user = await fetchUser()
const posts = await fetchPosts()
const comments = await fetchComments()
return
}
// Correct: Parallel fetching
async function Page() {
const [user, posts, comments] = await Promise.all([
fetchUser(),
fetchPosts(),
fetchComments()
])
return
}
```
Strategic Suspense Boundaries
```typescript
// Stream content as it becomes available
function Page() {
return (
)
}
```
---
3. Bundle Size Optimization (CRITICAL)
Quick Reference
bundle-barrel-imports- Import directly, avoid barrel filesbundle-dynamic-imports- Use next/dynamic for heavy componentsbundle-defer-third-party- Load analytics/logging after hydrationbundle-conditional- Load modules only when feature is activatedbundle-preload- Preload on hover/focus for perceived speed
Key Principles
Avoid Barrel File Imports
```typescript
// Incorrect: Imports entire library
import { Button } from '@/components'
import { formatDate } from '@/utils'
// Correct: Direct imports enable tree-shaking
import { Button } from '@/components/ui/button'
import { formatDate } from '@/utils/date'
```
Dynamic Imports
```typescript
import dynamic from 'next/dynamic'
// Load only when needed
const HeavyChart = dynamic(() => import('./HeavyChart'), {
loading: () =>
ssr: false
})
function Dashboard({ showChart }) {
return showChart ?
}
```
---
4. Server Components & Actions (HIGH)
Quick Reference
server-default-server- Components are Server Components by defaultserver-use-client-boundary- Add 'use client' only when neededserver-actions- Use Server Actions for mutationsserver-cache-react- Use React.cache() for per-request deduplicationserver-serialization- Minimize data passed to client components
Key Principles
Server Components by Default
```typescript
// Server Component (default) - can be async
async function ProductPage({ id }: { id: string }) {
const product = await db.product.findUnique({ where: { id } })
return
}
// Client Component - only when needed for interactivity
'use client'
function AddToCartButton({ productId }: { productId: string }) {
const [isPending, startTransition] = useTransition()
return (
onClick={() => startTransition(() => addToCart(productId))}
disabled={isPending}
>
Add to Cart
)
}
```
Server Actions
```typescript
// actions.ts
'use server'
export async function createPost(formData: FormData) {
const title = formData.get('title') as string
const content = formData.get('content') as string
await db.post.create({ data: { title, content } })
revalidatePath('/posts')
}
// Component usage
function CreatePostForm() {
return (
)
}
```
---
5. shadcn/ui Patterns (HIGH)
Quick Reference
shadcn-composition- Build on existing shadcn/ui primitivesshadcn-variants- Use class-variance-authority for component variantsshadcn-theme-integration- Use CSS custom properties for themingshadcn-accessibility- Leverage built-in accessibility from Radixshadcn-customization- Modify copied components, don't wrap excessively
Core Principles
shadcn/ui is built around:
- Open Code: Components are copied into your project, fully customizable
- Composition: Every component uses a common, composable interface
- Beautiful Defaults: Carefully chosen default styles
- Accessibility by Default: Built on Radix UI primitives
Component Installation
```bash
# Add components as needed
npx shadcn@latest add button
npx shadcn@latest add card
npx shadcn@latest add dialog
npx shadcn@latest add form
```
Building Custom Components
Composition Over Creation
```typescript
// Correct: Build on existing primitives
import { Card, CardHeader, CardTitle, CardContent } from '@/components/ui/card'
import { Badge } from '@/components/ui/badge'
interface ProductCardProps {
product: Product
onSelect?: () => void
}
function ProductCard({ product, onSelect }: ProductCardProps) {
return (
className="cursor-pointer hover:shadow-md transition-shadow"
onClick={onSelect}
>
{product.isNew &&
{product.description}
${product.price}
)
}
```
Using Variants with CVA
```typescript
import { cva, type VariantProps } from 'class-variance-authority'
import { cn } from '@/lib/utils'
const statusBadgeVariants = cva(
'inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-semibold',
{
variants: {
status: {
pending: 'bg-yellow-100 text-yellow-800',
active: 'bg-green-100 text-green-800',
inactive: 'bg-gray-100 text-gray-800',
error: 'bg-red-100 text-red-800',
},
},
defaultVariants: {
status: 'pending',
},
}
)
interface StatusBadgeProps
extends React.HTMLAttributes
VariantProps
label: string
}
function StatusBadge({ status, label, className, ...props }: StatusBadgeProps) {
return (
{label}
)
}
```
Common shadcn/ui Components
Forms with React Hook Form + Zod
```typescript
'use client'
import { zodResolver } from '@hookform/resolvers/zod'
import { useForm } from 'react-hook-form'
import * as z from 'zod'
import { Button } from '@/components/ui/button'
import {
Form,
FormControl,
FormDescription,
FormField,
FormItem,
FormLabel,
FormMessage,
} from '@/components/ui/form'
import { Input } from '@/components/ui/input'
const formSchema = z.object({
email: z.string().email('Invalid email address'),
password: z.string().min(8, 'Password must be at least 8 characters'),
})
function LoginForm() {
const form = useForm
resolver: zodResolver(formSchema),
defaultValues: {
email: '',
password: '',
},
})
function onSubmit(values: z.infer
console.log(values)
}
return (
control={form.control}
name="email"
render={({ field }) => (
)}
/>
control={form.control}
name="password"
render={({ field }) => (
)}
/>
)
}
```
Dialog/Modal Pattern
```typescript
import {
Dialog,
DialogContent,
DialogDescription,
DialogFooter,
DialogHeader,
DialogTitle,
DialogTrigger,
} from '@/components/ui/dialog'
import { Button } from '@/components/ui/button'
function ConfirmDialog({
onConfirm,
title,
description
}: {
onConfirm: () => void
title: string
description: string
}) {
return (
Confirm
)
}
```
Data Table with Tanstack Table
```typescript
import {
Table,
TableBody,
TableCell,
TableHead,
TableHeader,
TableRow,
} from '@/components/ui/table'
import {
ColumnDef,
flexRender,
getCoreRowModel,
useReactTable,
} from '@tanstack/react-table'
interface DataTableProps
columns: ColumnDef
data: TData[]
}
function DataTable
columns,
data,
}: DataTableProps
const table = useReactTable({
data,
columns,
getCoreRowModel: getCoreRowModel(),
})
return (
{table.getHeaderGroups().map((headerGroup) => ( {headerGroup.headers.map((header) => ( {flexRender( header.column.columnDef.header, header.getContext() )} ))} ))} {table.getRowModel().rows.map((row) => ( {row.getVisibleCells().map((cell) => ( {flexRender(cell.column.columnDef.cell, cell.getContext())} ))} ))}
)
}
```
---
6. State Management (MEDIUM-HIGH)
Quick Reference
state-local-first- Use useState/useReducer for local statestate-context-static- Use Context for infrequently changing datastate-derived-compute- Compute derived values, don't store themstate-url-state- Use URL for shareable/bookmarkable statestate-server-state- Use SWR/TanStack Query for server state
Key Principles
Avoid Derived State
```typescript
// Incorrect: Storing derived state
function ProductList({ products }) {
const [items, setItems] = useState(products)
const [count, setCount] = useState(products.length) // Derived!
// Bug: count can get out of sync with items
}
// Correct: Compute derived values
function ProductList({ products }) {
const [items, setItems] = useState(products)
const count = items.length // Always in sync
}
```
URL State for Filters/Pagination
```typescript
'use client'
import { useSearchParams, useRouter } from 'next/navigation'
function ProductFilters() {
const searchParams = useSearchParams()
const router = useRouter()
const category = searchParams.get('category') || 'all'
function setCategory(newCategory: string) {
const params = new URLSearchParams(searchParams)
params.set('category', newCategory)
router.push(?${params.toString()})
}
return (
{/ options /}
)
}
```
---
7. Motion & Animations (MEDIUM)
Quick Reference
motion-purposeful- Animations should enhance UX, not distractmotion-performance- Use transform/opacity, avoid layout triggersmotion-reduced-motion- Respect prefers-reduced-motionmotion-layout-id- Use layoutId for shared element transitionsmotion-exit-animations- Use AnimatePresence for exit animationsmotion-variants- Define reusable animation states
Installation
```bash
npm install motion
```
Core Principles
Motion (formerly Framer Motion) provides declarative animations that enhance user experience.
Basic Animations
```typescript
'use client'
import { motion } from 'motion/react'
function FadeInCard({ children }: { children: React.ReactNode }) {
return (
initial={{ opacity: 0, y: 20 }}
animate={{ opacity: 1, y: 0 }}
transition={{ duration: 0.3 }}
className="rounded-lg border p-4"
>
{children}
)
}
```
Interaction States
```typescript
function InteractiveButton({ children }: { children: React.ReactNode }) {
return (
whileHover={{ scale: 1.02 }}
whileTap={{ scale: 0.98 }}
transition={{ type: 'spring', stiffness: 400, damping: 17 }}
className="px-4 py-2 bg-primary text-primary-foreground rounded-md"
>
{children}
)
}
```
Exit Animations with AnimatePresence
```typescript
import { motion, AnimatePresence } from 'motion/react'
function NotificationList({ notifications }: { notifications: Notification[] }) {
return (
{notifications.map((notification) => (
key={notification.id}
initial={{ opacity: 0, x: 50 }}
animate={{ opacity: 1, x: 0 }}
exit={{ opacity: 0, x: -50 }}
transition={{ duration: 0.2 }}
>
))}
)
}
```
Shared Element Transitions
```typescript
function ProductGrid({ products }: { products: Product[] }) {
const [selected, setSelected] = useState
return (
<>
{products.map((product) => ( key={product.id} layoutId={ onClick={() => setSelected(product)} className="cursor-pointer" > ))} product-${product.id}}
{selected && (
layoutId={product-${selected.id}}
className="fixed inset-0 flex items-center justify-center"
>
)}
)
}
```
Reusable Variants
```typescript
const fadeInUp = {
initial: { opacity: 0, y: 20 },
animate: { opacity: 1, y: 0 },
exit: { opacity: 0, y: -20 },
}
const staggerContainer = {
animate: {
transition: {
staggerChildren: 0.1,
},
},
}
function StaggeredList({ items }: { items: string[] }) {
return (
{items.map((item, i) => (
{item}
))}
)
}
```
Scroll-Triggered Animations
```typescript
import { motion, useInView } from 'motion/react'
import { useRef } from 'react'
function ScrollReveal({ children }: { children: React.ReactNode }) {
const ref = useRef(null)
const isInView = useInView(ref, { once: true, margin: '-100px' })
return (
ref={ref}
initial={{ opacity: 0, y: 50 }}
animate={isInView ? { opacity: 1, y: 0 } : { opacity: 0, y: 50 }}
transition={{ duration: 0.5 }}
>
{children}
)
}
```
Respecting Reduced Motion
```typescript
import { motion, useReducedMotion } from 'motion/react'
function AccessibleAnimation({ children }: { children: React.ReactNode }) {
const shouldReduceMotion = useReducedMotion()
return (
initial={{ opacity: 0, y: shouldReduceMotion ? 0 : 20 }}
animate={{ opacity: 1, y: 0 }}
transition={{ duration: shouldReduceMotion ? 0 : 0.3 }}
>
{children}
)
}
```
Performance Tips
- Use
transformandopacityfor smooth 60fps animations - Set
willChangeprop for complex animations - Keep exit animations short (under 300ms)
- Use
useInViewto lazy-load animations - Avoid animating
width,height,top,leftdirectly
---
8. Re-render Optimization (MEDIUM)
Quick Reference
rerender-memo- Extract expensive work into memoized componentsrerender-usememo- Memoize expensive calculationsrerender-usecallback- Stabilize callback referencesrerender-dependencies- Use primitive dependencies in effectsrerender-transitions- Use startTransition for non-urgent updates
Key Principles
Memoization for Expensive Components
```typescript
import { memo } from 'react'
const ExpensiveList = memo(function ExpensiveList({
items
}: {
items: Item[]
}) {
return (
{items.map(item => (
))}
)
})
```
Stable Callbacks
```typescript
function Parent() {
const [count, setCount] = useState(0)
// Stable reference - won't cause child re-renders
const handleClick = useCallback(() => {
setCount(c => c + 1)
}, [])
return
}
```
Non-Urgent Updates with Transitions
```typescript
function SearchResults() {
const [query, setQuery] = useState('')
const [results, setResults] = useState([])
const [isPending, startTransition] = useTransition()
function handleChange(e: React.ChangeEvent
setQuery(e.target.value) // Urgent: update input immediately
startTransition(() => {
setResults(filterResults(e.target.value)) // Non-urgent: can be interrupted
})
}
return (
<>
{isPending &&
)
}
```
---
9. Accessibility (MEDIUM)
Quick Reference
a11y-semantic-html- Use correct HTML elementsa11y-keyboard-nav- Ensure keyboard navigabilitya11y-aria-labels- Add descriptive labels for screen readersa11y-focus-management- Manage focus in modals and dynamic contenta11y-color-contrast- Ensure sufficient color contrast
Key Principles
Semantic HTML
```typescript
// Incorrect: div soup
// Correct: semantic button
```
Focus Management in Modals
```typescript
function Modal({ isOpen, onClose, children }) {
const closeButtonRef = useRef
useEffect(() => {
if (isOpen) {
closeButtonRef.current?.focus()
}
}, [isOpen])
return (
{children}
Close
)
}
```
Skip Links
```typescript
function Layout({ children }) {
return (
<>
href="#main-content"
className="sr-only focus:not-sr-only focus:absolute focus:top-4 focus:left-4"
>
Skip to main content
)
}
```
---
10. TypeScript Patterns (MEDIUM)
Quick Reference
ts-strict-mode- Enable strict TypeScript configurationts-component-props- Define explicit prop interfacests-generics- Use generics for reusable componentsts-discriminated-unions- Use for state machinests-infer-when-possible- Let TypeScript infer when obvious
Key Principles
Component Props
```typescript
interface ButtonProps extends React.ButtonHTMLAttributes
variant?: 'default' | 'destructive' | 'outline'
size?: 'sm' | 'md' | 'lg'
isLoading?: boolean
}
function Button({
variant = 'default',
size = 'md',
isLoading,
children,
disabled,
...props
}: ButtonProps) {
return (
disabled={disabled || isLoading}
{...props}
>
{isLoading ?
)
}
```
Discriminated Unions for State
```typescript
type AsyncState
| { status: 'idle' }
| { status: 'loading' }
| { status: 'success'; data: T }
| { status: 'error'; error: Error }
function useAsync
const [state, setState] = useState
// TypeScript knows exact shape based on status
if (state.status === 'success') {
return state.data // TypeScript knows data exists
}
}
```
Generic Components
```typescript
interface SelectProps
options: T[]
value: T
onChange: (value: T) => void
getLabel: (option: T) => string
getValue: (option: T) => string
}
function Select
return (
value={getValue(value)}
onChange={(e) => {
const selected = options.find(o => getValue(o) === e.target.value)
if (selected) onChange(selected)
}}
>
{options.map((option) => (
{getLabel(option)}
))}
)
}
```
---
React 19+ Features
New Hooks
useActionState - Form state management
```typescript
'use client'
import { useActionState } from 'react'
function SubscribeForm() {
const [state, formAction, isPending] = useActionState(
async (prevState, formData) => {
const email = formData.get('email')
const result = await subscribe(email)
return result
},
null
)
return (
{isPending ? 'Subscribing...' : 'Subscribe'}
{state?.error && {state.error}
)
}
```
useOptimistic - Optimistic UI updates
```typescript
'use client'
import { useOptimistic } from 'react'
function TodoList({ todos }: { todos: Todo[] }) {
const [optimisticTodos, addOptimisticTodo] = useOptimistic(
todos,
(state, newTodo: Todo) => [...state, newTodo]
)
async function addTodo(formData: FormData) {
const title = formData.get('title') as string
const newTodo = { id: crypto.randomUUID(), title, completed: false }
addOptimisticTodo(newTodo) // Immediately show in UI
await createTodo(title) // Then persist to server
}
return (
<>
{optimisticTodos.map(todo => (
))}
)
}
```
use - Async resource reading
```typescript
import { use, Suspense } from 'react'
async function fetchUser(id: string): Promise
const res = await fetch(/api/users/${id})
return res.json()
}
function UserProfile({ userPromise }: { userPromise: Promise
const user = use(userPromise) // Suspends until resolved
return
}
function Page({ userId }: { userId: string }) {
const userPromise = fetchUser(userId)
return (
)
}
```
---
Project Structure
```
src/
βββ app/ # Next.js App Router
β βββ layout.tsx
β βββ page.tsx
β βββ (routes)/
βββ components/
β βββ ui/ # shadcn/ui components
β β βββ button.tsx
β β βββ card.tsx
β β βββ ...
β βββ features/ # Feature-specific components
β βββ auth/
β βββ dashboard/
βββ hooks/ # Custom hooks
βββ lib/ # Utilities
β βββ utils.ts # cn() helper, etc.
β βββ validations.ts # Zod schemas
βββ actions/ # Server Actions
βββ types/ # TypeScript types
```
---
References
- [React Documentation](https://react.dev)
- [Next.js Documentation](https://nextjs.org)
- [shadcn/ui Documentation](https://ui.shadcn.com)
- [Motion Documentation](https://motion.dev)
- [Radix UI Primitives](https://radix-ui.com)
- [TanStack Query](https://tanstack.com/query)
- [Tailwind CSS](https://tailwindcss.com)
More from this repository10
gitlab code review skill from dedalus-erp-pas/foundation-skills
postgres skill from dedalus-erp-pas/foundation-skills
article-extractor skill from dedalus-erp-pas/foundation-skills
Crafts distinctive, production-grade frontend interfaces with exceptional design quality, generating creative and polished web components and UI layouts.
Generates customized design system rules to automate Figma-to-code workflows, ensuring consistent UI/UX conventions and patterns across design and development teams.
Provides comprehensive Vue.js 3 best practices guidelines for writing idiomatic, maintainable code using Composition API, Tailwind CSS, and PrimeVue.
Generates professional, user-friendly changelogs by automatically transforming git commits into clear, categorized release notes.
Performs comprehensive web UI review by analyzing code, accessibility, and design against industry guidelines with auto-fix capabilities.
Automates web testing and browser interactions using Playwright, enabling comprehensive website validation, form testing, and dynamic web application debugging.
Builds high-quality MCP servers that enable LLMs to interact with external services through well-designed, discoverable, and context-aware tools.