# nextjs-patterns

> Provides comprehensive Next.js App Router patterns including server/client components, data fetching, routing, layouts, metadata, and performance optimization.

- Author: Jason
- Repository: satinsiders/vibe-devops-portal
- Version: 20260130123934
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/satinsiders/vibe-devops-portal
- Web: https://mule.run/skillshub/@@satinsiders/vibe-devops-portal~nextjs-patterns:20260130123934

---

---
name: nextjs-patterns
description: Provides comprehensive Next.js App Router patterns including server/client components, data fetching, routing, layouts, metadata, and performance optimization.
---

# Next.js Patterns

Comprehensive guide to Next.js App Router patterns and best practices.

## App Router Structure

### Directory Organization
- Route groups: `(name)/` - organize without affecting URL
- Dynamic routes: `[id]/` - URL parameters
- Catch-all: `[...slug]/` - match multiple segments
- Optional catch-all: `[[...slug]]/`
- Parallel routes: `@modal/` - render multiple pages
- Intercepting routes: `(.)modal/` - intercept navigation

### Special Files
- `layout.tsx` - Shared UI for route segment
- `page.tsx` - Unique UI for route
- `loading.tsx` - Loading UI (Suspense boundary)
- `error.tsx` - Error UI (Error boundary)
- `not-found.tsx` - 404 UI
- `route.ts` - API endpoint
- `template.tsx` - Re-rendered on navigation
- `default.tsx` - Fallback for parallel routes

## Server vs Client Components

### Server Components (Default)
- Default for all components
- Can fetch data directly
- Access backend resources
- Reduce client bundle
- Cannot use hooks or browser APIs

### Client Components
- Opt-in with `'use client'`
- Can use hooks (useState, useEffect)
- Access browser APIs
- Handle user interactions
- Subscribe to events

### When to Use
- Server: Data fetching, backend resources, SEO
- Client: Interactivity, hooks, browser APIs, event listeners

## Data Fetching Patterns

### Server Component Fetching
- Async components
- Direct database access
- No API route needed
- Automatic request deduplication
- Parallel and sequential patterns

### Caching Strategies
- `force-cache` - Cache permanently (default)
- `no-store` - Fetch every request
- `revalidate: seconds` - ISR pattern
- Tag-based revalidation with `revalidateTag()`

### Client Fetching
- Use React Query or SWR
- For dynamic data that changes frequently
- User-specific data
- Real-time updates

## Routing Patterns

### Navigation
- `Link` component for client-side navigation
- `useRouter` hook for programmatic navigation
- `redirect()` for server-side redirects
- `usePathname()` for current path

### Route Groups
Group routes without affecting URL structure
- `(marketing)/` - Marketing pages
- `(dashboard)/` - Dashboard pages
- Share layouts within groups

### Dynamic Routes
- Single: `[id]/page.tsx` - `/posts/123`
- Catch-all: `[...slug]/page.tsx` - `/docs/a/b/c`
- Optional: `[[...slug]]/page.tsx` - `/shop` or `/shop/a/b`

## Layout Patterns

### Nested Layouts
- Root layout required (html, body)
- Nested layouts inherit from parent
- Layouts don't remount on navigation
- Share state between route segments

### Template vs Layout
- Layout: Persists across navigation
- Template: Remounts on navigation
- Use template for: animations, user-specific data

## Metadata & SEO

### Static Metadata
Export metadata object from page/layout

### Dynamic Metadata
Export generateMetadata function with params

### Sitemap & Robots
- `app/sitemap.ts` - Generate sitemap
- `app/robots.ts` - Generate robots.txt

## API Routes

### Route Handlers
- `route.ts` in app directory
- Export HTTP method handlers: GET, POST, PUT, PATCH, DELETE
- Receive Request, return Response
- Server-only code

### Request/Response
- Access request: headers, body, params
- Return JSON: `NextResponse.json()`
- Set status: `NextResponse.json(data, { status })`
- Set headers: `NextResponse.next()` with headers

## Server Actions

### Form Actions
- Server functions called from client
- Use `'use server'` directive
- Progressive enhancement
- Handle form submissions
- Revalidate data after mutations

### Usage
- Inline in Server Components
- Separate file with `'use server'`
- Call from Client Components
- Return serializable data

## Streaming & Suspense

### Streaming Benefits
- Progressive rendering
- Faster time to first byte
- Better perceived performance

### Implementation
- `loading.tsx` - Route-level suspense
- `<Suspense>` - Component-level
- Stream data with async components

## Middleware

### Use Cases
- Authentication checks
- Redirects based on conditions
- Rewrite URLs
- Add headers
- A/B testing

### Configuration
- Create `middleware.ts` in root
- Export default function
- Export config with matcher
- Runs before route handlers

## Image Optimization

### Next Image Component
- Automatic optimization
- Lazy loading by default
- Prevents layout shift
- Responsive images

### Configuration
- Remote patterns for external images
- Loader for custom CDN
- Device sizes and breakpoints

## Environment Variables

### Types
- Public: `NEXT_PUBLIC_*` - Available in browser
- Private: No prefix - Server-only

### Access
- Server: `process.env.VAR_NAME`
- Client: Only `NEXT_PUBLIC_*` vars

## Performance Optimization

### Code Splitting
- Automatic route-based splitting
- Dynamic imports for components
- `next/dynamic` with loading state

### Bundle Analysis
- Use `@next/bundle-analyzer`
- Check page weights
- Identify large dependencies

### Font Optimization
- Use `next/font` for local fonts
- Automatic font subsetting
- Zero layout shift

## Authentication Patterns

### Session Management
- Use middleware to check auth
- Protect routes based on session
- Redirect unauthenticated users

### Protected Routes
- Check auth in middleware
- Server Component guards
- API route protection

## Error Handling

### Error Boundaries
- `error.tsx` - Catches errors in segment
- `global-error.tsx` - Catches root errors
- Access error and reset function

### Not Found
- `not-found.tsx` - Custom 404 page
- `notFound()` - Programmatically trigger

## Testing

### Unit Tests
- Test Server Components as async functions
- Test Client Components with React Testing Library
- Mock API routes and server actions

### E2E Tests
- Use Playwright
- Test full user flows
- Test with production build

## Deployment

### Vercel (Recommended)
- Automatic deployments
- Preview deployments for PRs
- Edge functions
- Analytics

### Self-Hosted
- Build with `next build`
- Start with `next start`
- Use Node.js server
- Configure environment variables

### Docker
- Multi-stage build
- Production dependencies only
- Optimize layer caching

## Best Practices

### DO
- Use Server Components by default
- Minimize client bundle
- Leverage automatic code splitting
- Use Image component for images
- Implement proper error boundaries
- Use metadata for SEO
- Stream when possible
- Cache appropriately

### DON'T
- Make everything a Client Component
- Fetch data in Client Components when Server works
- Use old Pages Router patterns
- Ignore metadata for SEO
- Skip error handling
- Forget loading states
- Over-use client-side state

## Migration from Pages Router

### Key Differences
- App Router uses Server Components
- File-based routing in `app/` directory
- Different data fetching patterns
- Layouts replace _app and _document
- New metadata API

### Migration Strategy
- Incremental migration supported
- Move routes one at a time
- Update data fetching patterns
- Migrate layouts and error handling