DEV Community: jordan wilfry

Next.js Data Fetching Patterns: Server Actions, API Routes, and React Query

jordan wilfry — Sat, 17 Jan 2026 22:46:56 +0000

Building Modern, Performant Data Layers in Next.js 15

Data fetching in Next.js 15 has evolved dramatically from the traditional useEffect and fetch patterns. With Server Actions enabling direct server-side mutations, API Routes providing RESTful endpoints, and React Query offering sophisticated client-side state management, developers now face a crucial question: which pattern should I use and when? Many intermediate developers struggle with choosing the right data fetching strategy, implementing efficient caching, handling optimistic updates, and building forms that feel instant while remaining reliable.

This comprehensive guide explores modern data fetching patterns in Next.js 15. You'll master Server Actions for seamless form handling and mutations, understand when to use API Routes versus direct database access, implement sophisticated caching strategies that balance freshness with performance, build CRUD operations that feel instant with optimistic updates, and integrate React Query for advanced client-side state management. By the end, you'll architect data layers that are both performant and maintainable, handling everything from simple forms to complex real-time dashboards.

Prerequisites

Before diving into advanced data fetching patterns, ensure you have:

Next.js 15 installed - Latest version with stable Server Actions
TypeScript knowledge - Interfaces, types, and async/await
React fundamentals - Hooks, state management, component composition
HTTP concepts - Understanding of REST APIs, status codes, headers
Database basics - SQL or NoSQL familiarity helpful
Promise handling - async/await, Promise.all, error handling
Form handling experience - Basic HTML forms and validation
Node.js 18.17+ and a package manager (npm/yarn/pnpm)

The Evolution of Data Fetching in Next.js

Data fetching in Next.js has evolved dramatically with the App Router. Gone are the days of getServerSideProps and getStaticProps. The modern Next.js paradigm embraces Server Components for data fetching, Server Actions for mutations, and sophisticated caching strategies that blur the line between static and dynamic content.

Many developers struggle with choosing the right data fetching pattern: Should you use Server Actions or API routes? When should you implement React Query? How do you handle optimistic updates? What's the best caching strategy? This comprehensive guide answers these questions and more, providing you with battle-tested patterns for building production-ready applications.

You'll learn how to fetch data efficiently in Server Components, handle form submissions with Server Actions, implement optimistic UI updates, build robust API routes, integrate React Query for client-side state management, and master Next.js caching strategies. By the end, you'll confidently choose the right data fetching pattern for any scenario and implement CRUD operations that feel instant while maintaining data integrity.

Prerequisites

Before diving into advanced data fetching patterns, ensure you have:

Next.js 15 with App Router - Fresh installation recommended
Understanding of Server and Client Components - Review Day 1 article if needed
TypeScript proficiency - Comfortable with types and interfaces
Database knowledge - Basic SQL or NoSQL understanding
HTTP methods - Understanding of REST principles (GET, POST, PUT, DELETE)
React hooks experience - useState, useEffect, useTransition
Async/await familiarity - Promise handling and error management
Node.js 18.17+ with npm/yarn/pnpm installed

The Evolution of Data Fetching in Next.js

Data fetching in Next.js 15 represents a paradigm shift from traditional patterns. Instead of creating API routes for every operation and fetching data on the client, you now have powerful server-side primitives that eliminate entire categories of boilerplate code. However, this shift introduces new questions: When should you use Server Actions versus API routes? How do you handle form submissions without JavaScript? What's the best way to implement optimistic updates? How do you manage cache invalidation across server and client boundaries?

This comprehensive guide explores modern data fetching patterns in Next.js 15. You'll master Server Actions for form handling and mutations, understand when to use traditional API routes, implement React Query for advanced client-side state management, build complete CRUD operations with proper error handling, create optimistic UI updates for instant feedback, and design robust caching strategies. By the end, you'll confidently choose the right data fetching pattern for any scenario and build applications that feel lightning-fast while remaining reliable.

Prerequisites

Before diving into advanced data fetching patterns, ensure you have:

Next.js 15 project setup - App Router configured and running
Understanding of Server Components - Review Day 1's article if needed
TypeScript basics - Types, interfaces, and async/await
HTTP methods knowledge - GET, POST, PUT, DELETE semantics
Database or API access - For testing CRUD operations
React hooks experience - useState, useEffect, useTransition
Basic understanding of REST APIs - Request/response patterns
Optional: React Query knowledge - Helpful but not required

The Evolution of Data Fetching in Next.js

Data fetching in Next.js has evolved dramatically with the App Router. Gone are the days of relying solely on getServerSideProps and getStaticProps. Next.js 15 introduces powerful new primitives: Server Actions for mutations, enhanced fetch API with automatic caching, and seamless integration with libraries like React Query for complex client-side state management.

This comprehensive guide explores modern data fetching patterns in Next.js 15. You'll learn how to perform CRUD operations using Server Actions, implement optimistic updates for instant UI feedback, manage complex caching strategies, integrate third-party libraries like React Query, and handle forms with progressive enhancement. By mastering these patterns, you'll build applications that feel instant while maintaining data consistency and proper error handling.

Prerequisites

Before diving into advanced data fetching patterns, ensure you have:

Next.js 15 installed - Latest stable version with App Router
Understanding of Server and Client Components - Know when to use each
TypeScript knowledge - Types, interfaces, and async/await
React fundamentals - Hooks, state management, and component lifecycle
HTTP basics - Understanding of REST principles and status codes
Database or API setup - For testing CRUD operations (PostgreSQL, MongoDB, or mock API)
Knowledge of async/await - Promises and asynchronous JavaScript

The Modern Data Fetching Landscape

Next.js 15 revolutionizes data fetching by providing multiple approaches, each optimized for different use cases. Gone are the days when you had to choose between client-side fetching with useEffect or building API routes for every data operation. Now you have Server Components for initial data loading, Server Actions for mutations, Route Handlers for external API integration, and the option to integrate React Query for advanced client-side caching.

Understanding when and how to use each pattern is crucial for building performant, maintainable applications. This guide explores the complete data fetching landscape: direct database access in Server Components, Server Actions for mutations and form handling, Route Handlers for public APIs, and React Query integration for complex client-side data management. You'll learn to implement full CRUD operations, handle optimistic updates, manage caching strategies, and build forms that work with and without JavaScript.

Prerequisites

Before diving into data fetching patterns, ensure you have:

Next.js 15 project setup - App Router with TypeScript
Understanding of async/await - Promise handling and async functions
React Server Components knowledge - Understanding from previous article recommended
HTTP methods familiarity - GET, POST, PUT, DELETE operations
Basic database knowledge - SQL or NoSQL concepts
Form handling experience - Understanding of form submission basics
TypeScript fundamentals - Types, interfaces, and async/await

The Evolution of Data Fetching in Next.js

Next.js 15 introduces a paradigm shift in how we handle data mutations and server-side logic. While traditional approaches relied heavily on API routes and client-side data fetching libraries, the App Router brings Server Actions—a revolutionary way to handle mutations directly from Server Components without explicit API endpoints.

Understanding the Data Fetching Landscape

Modern Next.js applications have multiple options for data fetching:

Server Components - Direct database queries and API calls on the server
Server Actions - Server-side mutations called from Client Components
Route Handlers - Traditional API endpoints for REST APIs
Client-side fetching - Using libraries like React Query for complex client state

Each approach has specific use cases, and understanding when to use each pattern is crucial for building efficient applications.

Prerequisites

Before diving into data fetching patterns, ensure you have:

Next.js 15 installed - With App Router enabled
TypeScript experience - Understanding types and interfaces
React fundamentals - Hooks, props, component lifecycle
HTTP knowledge - REST principles, status codes, request methods
Database basics - SQL or NoSQL query concepts
Async JavaScript - Promises, async/await patterns
Form handling experience - HTML forms and validation

Server Actions: The Modern Way to Handle Mutations

Server Actions are asynchronous functions that run on the server. They provide a seamless way to handle form submissions and mutations without creating API routes.

Basic Server Action

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

import { revalidatePath } from 'next/cache';
import { redirect } from 'next/navigation';

export async function createPost(formData: FormData) {
  const title = formData.get('title') as string;
  const content = formData.get('content') as string;

  // Validate input
  if (!title || title.length < 3) {
    return { error: 'Title must be at least 3 characters' };
  }

  if (!content || content.length < 10) {
    return { error: 'Content must be at least 10 characters' };
  }

  try {
    // Create post in database
    const post = await db.posts.create({
      data: { title, content }
    });

    // Revalidate the posts page to show new post
    revalidatePath('/posts');

    // Redirect to the new post
    redirect(`/posts/${post.id}`);
  } catch (error) {
    return { error: 'Failed to create post' };
  }
}

// app/posts/create/page.tsx
import { createPost } from '@/app/actions/posts';
import { SubmitButton } from '@/components/SubmitButton';

export default function CreatePostPage() {
  return (
    <form action={createPost}>
      <div>
        <label htmlFor="title">Title</label>
        <input
          type="text"
          id="title"
          name="title"
          required
        />
      </div>

      <div>
        <label htmlFor="content">Content</label>
        <textarea
          id="content"
          name="content"
          rows={10}
          required
        />
      </div>

      <SubmitButton />
    </form>
  );
}

// components/SubmitButton.tsx
'use client';

import { useFormStatus } from 'react-dom';

export function SubmitButton() {
  const { pending } = useFormStatus();

  return (
    <button type="submit" disabled={pending}>
      {pending ? 'Creating...' : 'Create Post'}
    </button>
  );
}

Server Actions with useFormState

For better error handling and user feedback:

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

import { revalidatePath } from 'next/cache';

export type FormState = {
  message: string;
  errors?: {
    title?: string[];
    content?: string[];
  };
  success?: boolean;
};

export async function createPost(
  prevState: FormState,
  formData: FormData
): Promise<FormState> {
  const title = formData.get('title') as string;
  const content = formData.get('content') as string;

  // Validation
  const errors: FormState['errors'] = {};

  if (!title || title.length < 3) {
    errors.title = ['Title must be at least 3 characters'];
  }

  if (!content || content.length < 10) {
    errors.content = ['Content must be at least 10 characters'];
  }

  if (Object.keys(errors).length > 0) {
    return {
      message: 'Validation failed',
      errors,
    };
  }

  try {
    await db.posts.create({
      data: { title, content }
    });

    revalidatePath('/posts');

    return {
      message: 'Post created successfully!',
      success: true,
    };
  } catch (error) {
    return {
      message: 'Failed to create post',
      errors: { title: ['Database error occurred'] },
    };
  }
}

// app/posts/create/page.tsx
'use client';

import { useFormState } from 'react-dom';
import { createPost, FormState } from '@/app/actions/posts';
import { SubmitButton } from '@/components/SubmitButton';
import { useEffect } from 'react';
import { useRouter } from 'next/navigation';

const initialState: FormState = {
  message: '',
};

export default function CreatePostPage() {
  const [state, formAction] = useFormState(createPost, initialState);
  const router = useRouter();

  useEffect(() => {
    if (state.success) {
      router.push('/posts');
    }
  }, [state.success, router]);

  return (
    <form action={formAction}>
      <div>
        <label htmlFor="title">Title</label>
        <input
          type="text"
          id="title"
          name="title"
          required
        />
        {state.errors?.title && (
          <p className="error">{state.errors.title[0]}</p>
        )}
      </div>

      <div>
        <label htmlFor="content">Content</label>
        <textarea
          id="content"
          name="content"
          rows={10}
          required
        />
        {state.errors?.content && (
          <p className="error">{state.errors.content[0]}</p>
        )}
      </div>

      {state.message && !state.success && (
        <p className="error">{state.message}</p>
      )}

      <SubmitButton />
    </form>
  );
}

Progressive Enhancement with Server Actions

Server Actions work without JavaScript, providing excellent progressive enhancement:

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

import { revalidatePath } from 'next/cache';

export async function toggleTodo(formData: FormData) {
  const todoId = formData.get('todoId') as string;
  const completed = formData.get('completed') === 'true';

  await db.todos.update({
    where: { id: todoId },
    data: { completed: !completed }
  });

  revalidatePath('/todos');
}

export async function deleteTodo(formData: FormData) {
  const todoId = formData.get('todoId') as string;

  await db.todos.delete({
    where: { id: todoId }
  });

  revalidatePath('/todos');
}

// app/todos/page.tsx
import { toggleTodo, deleteTodo } from '@/app/actions/todos';

async function getTodos() {
  return db.todos.findMany();
}

export default async function TodosPage() {
  const todos = await getTodos();

  return (
    <div>
      <h1>My Todos</h1>
      <ul>
        {todos.map(todo => (
          <li key={todo.id}>
            <form action={toggleTodo} style={{ display: 'inline' }}>
              <input type="hidden" name="todoId" value={todo.id} />
              <input type="hidden" name="completed" value={String(todo.completed)} />
              <button type="submit">
                {todo.completed ? '✓' : '○'}
              </button>
            </form>

            <span style={{ 
              textDecoration: todo.completed ? 'line-through' : 'none' 
            }}>
              {todo.title}
            </span>

            <form action={deleteTodo} style={{ display: 'inline' }}>
              <input type="hidden" name="todoId" value={todo.id} />
              <button type="submit">Delete</button>
            </form>
          </li>
        ))}
      </ul>
    </div>
  );
}

Server Actions with useOptimistic

Provide instant feedback with optimistic updates:

// app/todos/TodoList.tsx
'use client';

import { useOptimistic } from 'react';
import { toggleTodo } from '@/app/actions/todos';

type Todo = {
  id: string;
  title: string;
  completed: boolean;
};

export function TodoList({ todos }: { todos: Todo[] }) {
  const [optimisticTodos, addOptimisticTodo] = useOptimistic(
    todos,
    (state, { id, completed }: { id: string; completed: boolean }) => {
      return state.map(todo =>
        todo.id === id ? { ...todo, completed } : todo
      );
    }
  );

  async function handleToggle(id: string, completed: boolean) {
    // Immediately update UI
    addOptimisticTodo({ id, completed: !completed });

    // Then perform server action
    const formData = new FormData();
    formData.append('todoId', id);
    formData.append('completed', String(completed));
    await toggleTodo(formData);
  }

  return (
    <ul>
      {optimisticTodos.map(todo => (
        <li key={todo.id}>
          <button onClick={() => handleToggle(todo.id, todo.completed)}>
            {todo.completed ? '✓' : '○'}
          </button>
          <span style={{ 
            textDecoration: todo.completed ? 'line-through' : 'none',
            opacity: todo.completed ? 0.6 : 1
          }}>
            {todo.title}
          </span>
        </li>
      ))}
    </ul>
  );
}

// app/todos/page.tsx
import { TodoList } from './TodoList';

async function getTodos() {
  return db.todos.findMany();
}

export default async function TodosPage() {
  const todos = await getTodos();

  return (
    <div>
      <h1>My Todos</h1>
      <TodoList todos={todos} />
    </div>
  );
}

API Routes: RESTful Endpoints

While Server Actions are preferred for mutations, Route Handlers are perfect for building RESTful APIs.

Complete CRUD API

// app/api/products/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { z } from 'zod';

const productSchema = z.object({
  name: z.string().min(3),
  price: z.number().positive(),
  description: z.string().optional(),
  categoryId: z.string(),
});

// GET /api/products - List all products
export async function GET(request: NextRequest) {
  try {
    const searchParams = request.nextUrl.searchParams;
    const category = searchParams.get('category');
    const page = parseInt(searchParams.get('page') || '1');
    const limit = parseInt(searchParams.get('limit') || '10');

    const where = category ? { categoryId: category } : {};

    const [products, total] = await Promise.all([
      db.products.findMany({
        where,
        skip: (page - 1) * limit,
        take: limit,
        include: { category: true },
      }),
      db.products.count({ where }),
    ]);

    return NextResponse.json({
      success: true,
      data: products,
      pagination: {
        page,
        limit,
        total,
        totalPages: Math.ceil(total / limit),
      },
    });
  } catch (error) {
    return NextResponse.json(
      { success: false, error: 'Failed to fetch products' },
      { status: 500 }
    );
  }
}

// POST /api/products - Create a product
export async function POST(request: NextRequest) {
  try {
    const body = await request.json();

    // Validate input
    const validatedData = productSchema.parse(body);

    // Check authorization (example)
    const authHeader = request.headers.get('authorization');
    if (!authHeader) {
      return NextResponse.json(
        { success: false, error: 'Unauthorized' },
        { status: 401 }
      );
    }

    const product = await db.products.create({
      data: validatedData,
    });

    return NextResponse.json(
      { success: true, data: product },
      { status: 201 }
    );
  } catch (error) {
    if (error instanceof z.ZodError) {
      return NextResponse.json(
        { success: false, error: 'Validation failed', details: error.errors },
        { status: 400 }
      );
    }

    return NextResponse.json(
      { success: false, error: 'Failed to create product' },
      { status: 500 }
    );
  }
}

// app/api/products/[id]/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { z } from 'zod';

const updateProductSchema = z.object({
  name: z.string().min(3).optional(),
  price: z.number().positive().optional(),
  description: z.string().optional(),
  categoryId: z.string().optional(),
});

interface RouteContext {
  params: { id: string };
}

// GET /api/products/[id] - Get single product
export async function GET(
  request: NextRequest,
  { params }: RouteContext
) {
  try {
    const product = await db.products.findUnique({
      where: { id: params.id },
      include: {
        category: true,
        reviews: {
          take: 5,
          orderBy: { createdAt: 'desc' },
        },
      },
    });

    if (!product) {
      return NextResponse.json(
        { success: false, error: 'Product not found' },
        { status: 404 }
      );
    }

    return NextResponse.json({
      success: true,
      data: product,
    });
  } catch (error) {
    return NextResponse.json(
      { success: false, error: 'Failed to fetch product' },
      { status: 500 }
    );
  }
}

// PATCH /api/products/[id] - Update product
export async function PATCH(
  request: NextRequest,
  { params }: RouteContext
) {
  try {
    const body = await request.json();
    const validatedData = updateProductSchema.parse(body);

    const product = await db.products.update({
      where: { id: params.id },
      data: validatedData,
    });

    return NextResponse.json({
      success: true,
      data: product,
    });
  } catch (error) {
    if (error instanceof z.ZodError) {
      return NextResponse.json(
        { success: false, error: 'Validation failed', details: error.errors },
        { status: 400 }
      );
    }

    return NextResponse.json(
      { success: false, error: 'Failed to update product' },
      { status: 500 }
    );
  }
}

// DELETE /api/products/[id] - Delete product
export async function DELETE(
  request: NextRequest,
  { params }: RouteContext
) {
  try {
    await db.products.delete({
      where: { id: params.id },
    });

    return NextResponse.json({
      success: true,
      message: 'Product deleted successfully',
    });
  } catch (error) {
    return NextResponse.json(
      { success: false, error: 'Failed to delete product' },
      { status: 500 }
    );
  }
}

API Route with Authentication

// lib/auth.ts
import { NextRequest } from 'next/server';
import { jwtVerify } from 'jose';

export async function verifyAuth(request: NextRequest) {
  const token = request.headers.get('authorization')?.replace('Bearer ', '');

  if (!token) {
    return null;
  }

  try {
    const secret = new TextEncoder().encode(process.env.JWT_SECRET);
    const { payload } = await jwtVerify(token, secret);
    return payload;
  } catch (error) {
    return null;
  }
}

// app/api/profile/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { verifyAuth } from '@/lib/auth';

export async function GET(request: NextRequest) {
  const user = await verifyAuth(request);

  if (!user) {
    return NextResponse.json(
      { success: false, error: 'Unauthorized' },
      { status: 401 }
    );
  }

  const profile = await db.users.findUnique({
    where: { id: user.id as string },
    select: {
      id: true,
      email: true,
      name: true,
      createdAt: true,
    },
  });

  return NextResponse.json({
    success: true,
    data: profile,
  });
}

export async function PATCH(request: NextRequest) {
  const user = await verifyAuth(request);

  if (!user) {
    return NextResponse.json(
      { success: false, error: 'Unauthorized' },
      { status: 401 }
    );
  }

  const body = await request.json();

  const updatedProfile = await db.users.update({
    where: { id: user.id as string },
    data: {
      name: body.name,
    },
    select: {
      id: true,
      email: true,
      name: true,
    },
  });

  return NextResponse.json({
    success: true,
    data: updatedProfile,
  });
}

React Query Integration for Client-Side Data Fetching

React Query (TanStack Query) provides powerful client-side state management for server data.

Setting Up React Query

// app/providers.tsx
'use client';

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { ReactNode, useState } from 'react';

export function Providers({ children }: { children: ReactNode }) {
  const [queryClient] = useState(
    () =>
      new QueryClient({
        defaultOptions: {
          queries: {
            staleTime: 60 * 1000, // 1 minute
            refetchOnWindowFocus: false,
          },
        },
      })
  );

  return (
    <QueryClientProvider client={queryClient}>
      {children}
    </QueryClientProvider>
  );
}

// app/layout.tsx
import { Providers } from './providers';

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Providers>
          {children}
        </Providers>
      </body>
    </html>
  );
}

Queries with React Query

// lib/api/products.ts
export async function fetchProducts(page: number = 1) {
  const res = await fetch(`/api/products?page=${page}&limit=10`);
  if (!res.ok) throw new Error('Failed to fetch products');
  return res.json();
}

export async function fetchProduct(id: string) {
  const res = await fetch(`/api/products/${id}`);
  if (!res.ok) throw new Error('Failed to fetch product');
  return res.json();
}

// app/products/ProductList.tsx
'use client';

import { useQuery } from '@tanstack/react-query';
import { fetchProducts } from '@/lib/api/products';
import { useState } from 'react';

export function ProductList() {
  const [page, setPage] = useState(1);

  const { data, isLoading, error } = useQuery({
    queryKey: ['products', page],
    queryFn: () => fetchProducts(page),
  });

  if (isLoading) {
    return <div>Loading products...</div>;
  }

  if (error) {
    return <div>Error loading products: {error.message}</div>;
  }

  return (
    <div>
      <div className="product-grid">
        {data.data.map((product: any) => (
          <div key={product.id} className="product-card">
            <h3>{product.name}</h3>
            <p>${product.price}</p>
          </div>
        ))}
      </div>

      <div className="pagination">
        <button
          onClick={() => setPage(p => Math.max(1, p - 1))}
          disabled={page === 1}
        >
          Previous
        </button>
        <span>Page {page} of {data.pagination.totalPages}</span>
        <button
          onClick={() => setPage(p => p + 1)}
          disabled={page >= data.pagination.totalPages}
        >
          Next
        </button>
      </div>
    </div>
  );
}

Mutations with React Query

// lib/api/products.ts
export async function createProduct(data: {
  name: string;
  price: number;
  description?: string;
  categoryId: string;
}) {
  const res = await fetch('/api/products', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(data),
  });

  if (!res.ok) throw new Error('Failed to create product');
  return res.json();
}

export async function updateProduct(id: string, data: Partial<{
  name: string;
  price: number;
  description: string;
  categoryId: string;
}>) {
  const res = await fetch(`/api/products/${id}`, {
    method: 'PATCH',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(data),
  });

  if (!res.ok) throw new Error('Failed to update product');
  return res.json();
}

export async function deleteProduct(id: string) {
  const res = await fetch(`/api/products/${id}`, {
    method: 'DELETE',
  });

  if (!res.ok) throw new Error('Failed to delete product');
  return res.json();
}

// app/products/CreateProductForm.tsx
'use client';

import { useMutation, useQueryClient } from '@tanstack/react-query';
import { createProduct } from '@/lib/api/products';
import { useState } from 'react';

export function CreateProductForm() {
  const queryClient = useQueryClient();
  const [name, setName] = useState('');
  const [price, setPrice] = useState('');
  const [categoryId, setCategoryId] = useState('');

  const mutation = useMutation({
    mutationFn: createProduct,
    onSuccess: () => {
      // Invalidate and refetch products list
      queryClient.invalidateQueries({ queryKey: ['products'] });
      // Reset form
      setName('');
      setPrice('');
      setCategoryId('');
    },
  });

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    mutation.mutate({
      name,
      price: parseFloat(price),
      categoryId,
    });
  };

  return (
    <form onSubmit={handleSubmit}>
      <div>
        <label>Name</label>
        <input
          value={name}
          onChange={e => setName(e.target.value)}
          required
        />
      </div>
>
        <label>Price</label>
        <input
          type="number"
          step="0.01"
          value={price}
          onChange={e => setPrice(e.target.value)}
          required
        />
      </div>

      <div>
        <label>Category ID</label>
        <input
          value={categoryId}
          onChange={e => setCategoryId(e.target.value)}
          required
        />
      </div>

      {mutation.error && (
        <p className="error">{mutation.error.message}</p>
      )}

      <button type="submit" disabled={mutation.isPending}>
        {mutation.isPending ? 'Creating...' : 'Create Product'}
      </button>

      {mutation.isSuccess && (
        <p className="success">Product created successfully!</p>
      )}
    </form>
  );
}

Optimistic Updates with React Query

// app/products/ProductCard.tsx
'use client';

import { useMutation, useQueryClient } from '@tanstack/react-query';
import { deleteProduct } from '@/lib/api/products';

type Product = {
  id: string;
  name: string;
  price: number;
};

export function ProductCard({ product }: { product: any }) {
  const queryClient = useQueryClient();

  const deleteMutation = useMutation({
    mutationFn: deleteProduct,
    onMutate: async (productId) => {
      // Cancel outgoing refetches
      await queryClient.cancelQueries({ queryKey: ['products'] });

      // Snapshot previous value
      const previousProducts = queryClient.getQueryData(['products']);

      // Optimistically update
      queryClient.setQueryData(['products'], (old: any) => ({
        ...old,
        data: old.data.filter((p: any) => p.id !== productId),
      }));

      // Return context for rollback
      return { previousProducts: previousData };
    },
    onError: (err, variables, context) => {
      // Rollback on error
      if (context?.previousProducts) {
        queryClient.setQueryData(['products', page], context.previousProducts);
      }
    },
    onSettled: () => {
      // Always refetch after error or success
      queryClient.invalidateQueries({ queryKey: ['products'] });
    },
  });

  return (
    <button
      onClick={() => mutation.mutate(productId)}
      disabled={mutation.isPending}
    >
      {mutation.isPending ? 'Deleting...' : 'Delete'}
    </button>
  );
}

Optimistic Updates with React Query

// app/products/ProductCard.tsx
'use client';

import { useMutation, useQueryClient } from '@tanstack/react-query';
import { deleteProduct } from '@/lib/api/products';

export function ProductCard({ product }: { product: any }) {
  const queryClient = useQueryClient();

  const deleteMutation = useMutation({
    mutationFn: deleteProduct,
    onMutate: async (productId) => {
      // Cancel outgoing refetches
      await queryClient.cancelQueries({ queryKey: ['products'] });

      // Snapshot previous value
      const previousProducts = queryClient.getQueryData(['products']);

      // Optimistically remove the product
      queryClient.setQueryData(['products'], (old: any) => ({
        ...old,
        data: old.data.filter((p: any) => p.id !== productId),
      }));

      return { previousProducts: data };
    },
    onError: (err, variables, context) => {
      // Rollback on error
      queryClient.setQueryData(['products'], context?.previousProducts);
    },
    onSettled: () => {
      // Refetch after error or success
      queryClient.invalidateQueries({ queryKey: ['products'] });
    },
  });

  return (
    <button
      onClick={() => mutation.mutate(productId)}
      disabled={mutation.isPending}
    >
      {mutation.isPending ? 'Deleting...' : 'Delete'}
    </button>
  );
}

Optimistic Updates with React Query

// app/products/ProductCard.tsx
'use client';

import { useMutation, useQueryClient } from '@tanstack/react-query';
import { updateProduct } from '@/lib/api/products';

type Product = {
  id: string;
  name: string;
  price: number;
  isFavorite: boolean;
};

export function ProductCard({ product }: { product: any }) {
  const queryClient = useQueryClient();

  const toggleFavorite = useMutation({
    mutationFn: (id: string) =>
      updateProduct(id, { isFavorite: !product.isFavorite }),

    // Optimistic update
    onMutate: async () => {
      // Cancel outgoing refetches
      await queryClient.cancelQueries({ queryKey: ['products'] });

      // Snapshot the previous value
      const previousProducts = queryClient.getQueryData(['products']);

      // Optimistically update to the new value
      queryClient.setQueryData(['products'], (old: any) => ({
        ...old,
        data: old.data.map((p: any) =>
          p.id === product.id
            ? { ...p, isFavorite: !p.isFavorite }
            : p
        ),
      }));

      return { previousProducts: previous };
    },
    onError: (err, variables, context) => {
      // Rollback on error
      if (context?.previousProducts) {
        queryClient.setQueryData(['products'], context.previousProducts);
      }
    },
    onSettled: () => {
      // Refetch after error or success
      queryClient.invalidateQueries({ queryKey: ['products'] });
    },
  });

  return (
    <button
      onClick={() => mutation.mutate(productId)}
      disabled={mutation.isPending}
    >
      {mutation.isPending ? 'Adding...' : 'Add to Cart'}
    </button>
  );
}

Optimistic Updates with React Query

// app/products/ProductItem.tsx
'use client';

import { useMutation, useQueryClient } from '@tanstack/react-query';
import { updateProduct } from '@/lib/api/products';

type Product = {
  id: string;
  name: string;
  price: number;
  stock: number;
};

export function ProductItem({ product }: { product: Product }) {
  const queryClient = useQueryClient();

  const mutation = useMutation({
    mutationFn: (newStock: number) =>
      updateProduct(product.id, { stock: newStock }),
    onMutate: async (newStock) => {
      // Cancel outgoing refetches
      await queryClient.cancelQueries({ queryKey: ['products'] });

      // Snapshot previous value
      const previousProducts = queryClient.getQueryData(['products']);

      // Optimistically update
      queryClient.setQueryData(['products'], (old: any) => ({
        ...old,
        data: old.data.map((p: any) =>
          p.id === product.id ? { ...p, stock: newStock } : p
        ),
      }));

      return { previousProducts };
    },
    onError: (err, variables, context) => {
      // Rollback on error
      queryClient.setQueryData(['products'], context?.previousProducts);
    },
    onSettled: () => {
      // Refetch after error or success
      queryClient.invalidateQueries({ queryKey: ['products'] });
    },
  });

  return (
    <button onClick={() => mutation.mutate(productId)}>
      {mutation.isPending ? 'Updating...' : 'Update Stock'}
    </button>
  );
}

Caching Strategies

Next.js 15 provides powerful caching mechanisms that work seamlessly with all data fetching approaches.

Fetch API Caching

// Revalidate every hour
async function getProducts() {
  const res = await fetch('https://api.example.com/products', {
    next: { revalidate: 3600 }
  });
  return res.json();
}

// Never cache (always fresh)
async function getCurrentUser() {
  const res = await fetch('https://api.example.com/user', {
    cache: 'no-store'
  });
  return res.json();
}

// Cache forever
async function getConfig() {
  const res = await fetch('https://api.example.com/config', {
    cache: 'force-cache'
  });
  return res.json();
}

Tag-Based Revalidation

// lib/data.ts
export async function getPost(slug: string) {
  const res = await fetch(`https://api.example.com/posts/${slug}`, {
    next: { 
      tags: [`post-${slug}`, 'posts'],
      revalidate: 3600
    }
  });
  return res.json();
}

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

import { revalidateTag } from 'next/cache';

export async function updatePost(slug: string, data: any) {
  await db.posts.update({
    where: { slug },
    data
  });

  // Revalidate specific post
  revalidateTag(`post-${slug}`);

  // Revalidate all posts list
  revalidateTag('posts');
}

Path-Based Revalidation

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

import { revalidatePath } from 'next/cache';

export async function createPost(data: any) {
  const post = await db.posts.create({ data });

  // Revalidate the posts list page
  revalidatePath('/posts');

  // Revalidate the new post page
  revalidatePath(`/posts/${post.slug}`);

  return post;
}

React Query Cache Integration

// hooks/useProducts.ts
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import { fetchProducts, updateProduct } from '@/lib/api/products';

export function useProducts(page: number) {
  return useQuery({
    queryKey: ['products', page],
    queryFn: () => fetchProducts(page),
    staleTime: 5 * 60 * 1000, // 5 minutes
  });
}

export function useUpdateProduct() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: ({ id, data }: { id: string; data: any }) =>
      updateProduct(id, data),
    onSuccess: (updatedProduct) => {
      // Update the product in the cache
      queryClient.setQueryData(
        ['product', updatedProduct.data.id],
        updatedProduct
      );

      // Invalidate products list to refetch
      queryClient.invalidateQueries({ queryKey: ['products'] });
    },
  });
}

Optimistic Updates: Building Instant UIs

Optimistic updates provide immediate feedback while the server processes the request.

Optimistic Updates with useOptimistic

// app/comments/CommentList.tsx
'use client';

import { useOptimistic } from 'react';
import { addComment, deleteComment } from '@/app/actions/comments';

type Comment = {
  id: string;
  text: string;
  author: string;
  pending?: boolean;
};

export function CommentList({ 
  comments: initialComments,
  postId
}: { 
  comments: Comment[];
  postId: string;
}) {
  const [optimisticComments, addOptimisticComment] = useOptimistic(
    initialComments,
    (state, newComment: Comment) => [...state, newComment]
  );

  async function handleAddComment(formData: FormData) {
    const text = formData.get('text') as string;

    // Immediately show the comment
    addOptimisticComment({
      id: crypto.randomUUID(),
      text,
      author: 'You',
      pending: true,
    });

    // Then submit to server
    await addComment(postId, text);
  }

  return (
    <div>
      <form action={handleAddComment}>
        <textarea name="text" required />
        <button type="submit">Add Comment</button>
      </form>

      <div className="comments">
        {optimisticComments.map(comment => (
          <div 
            key={comment.id}
            className={comment.pending ? 'pending' : ''}
          >
            <strong>{comment.author}</strong>
            <p>{comment.text}</p>
          </div>
        ))}
      </div>
    </div>
  );
}

Optimistic Updates with React Query

// hooks/useComments.ts
import { useMutation, useQueryClient } from '@tanstack/react-query';
import { addComment } from '@/lib/api/comments';

export function useAddComment(postId: string) {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: (text: string) => addComment(postId, text),
    onMutate: async (text) => {
      // Cancel outgoing refetches
      await queryClient.cancelQueries({ queryKey: ['comments', postId] });

      // Snapshot previous value
      const previousComments = queryClient.getQueryData(['comments', postId]);

      // Optimistically update
      queryClient.setQueryData(['comments', postId], (old: any) => [
        ...old,
        {
          id: crypto.randomUUID(),
          text,
          author: 'You',
          pending: true,
        },
      ]);

      return { previousComments };
    },
    onError: (err, newComment, context) => {
      // Rollback on error
      queryClient.setQueryData(
        ['comments', postId],
        context?.previousComments
      );
    },
    onSettled: () => {
      // Refetch after mutation
      queryClient.invalidateQueries({ queryKey: ['comments', postId] });
    },
  });
}

Best Practices Section

✅ Dos

Use Server Actions for form submissions - They work without JavaScript and provide excellent progressive enhancement:

// ✅ Good - Server Action
'use server';
export async function createPost(formData: FormData) {
  const title = formData.get('title');
  await db.posts.create({ data: { title } });
  revalidatePath('/posts');
}

Implement proper error handling - Always handle errors gracefully and provide user feedback:

// ✅ Good - Comprehensive error handling
export async function createPost(formData: FormData) {
  try {
    // Validation
    if (!title || title.length < 3) {
      return { error: 'Title too short' };
    }

    // Database operation
    await db.posts.create({ data: { title } });
    revalidatePath('/posts');

    return { success: true };
  } catch (error) {
    console.error('Create post error:', error);
    return { error: 'Failed to create post' };
  }
}

Use optimistic updates for better UX - Show immediate feedback while the server processes:

// ✅ Good - Optimistic update
const [optimisticLikes, addOptimisticLike] = useOptimistic(
  likes,
  (state, amount: number) => state + amount
);

Leverage React Query for complex client state - Use it for polling, infinite scroll, and complex caching:

// ✅ Good - React Query for real-time data
const { data } = useQuery({
  queryKey: ['notifications'],
  queryFn: fetchNotifications,
  refetchInterval: 30000, // Poll every 30 seconds
});

Cache strategically - Use appropriate caching strategies for different data types:

// ✅ Good - Strategic caching
// Static content - cache forever
fetch('/api/config', { cache: 'force-cache' });

// Dynamic content - revalidate periodically
fetch('/api/posts', { next: { revalidate: 60 } });

// User-specific - never cache
fetch('/api/user', { cache: 'no-store' });

❌ Don'ts

Don't use API routes when Server Actions suffice - Server Actions are simpler for mutations:

// ❌ Bad - Unnecessary API route
// /api/posts/route.ts
export async function POST(req) {
  const body = await req.json();
  await db.posts.create({ data: body });
  return Response.json({ success: true });
}

// ✅ Good - Server Action
'use server';
export async function createPost(formData: FormData) {
  await db.posts.create({ data: { title: formData.get('title') } });
  revalidatePath('/posts');
}

Don't forget to revalidate after mutations - Always revalidate affected paths or tags:

// ❌ Bad - No revalidation
export async function updatePost(id, data) {
  await db.posts.update({ where: { id }, data });
  // Users won't see changes!
}

// ✅ Good - Revalidate
export async function updatePost(id, data) {
  await db.posts.update({ where: { id }, data });
  revalidatePath('/posts');
  revalidateTag(`post-${id}`);
}

Don't expose sensitive data in API routes - Always validate authentication and authorization:

// ❌ Bad - No auth check
export async function GET() {
  const users = await db.users.findMany();
  return Response.json(users); // Exposes all user data!
}

// ✅ Good - Auth check
export async function GET(request) {
  const user = await verifyAuth(request);
  if (!user || user.role !== 'admin') {
    return Response.json({ error: 'Unauthorized' }, { status: 401 });
  }
  const users = await db.users.findMany();
  return Response.json(users);
}

Don't over-fetch data - Fetch only what you need:

// ❌ Bad - Fetches everything
const user = await db.users.findUnique({
  where: { id },
  include: { posts: true, comments: true, likes: true }
});

// ✅ Good - Selective fetching
const user = await db.users.findUnique({
  where: { id },
  select: { id: true, name: true, email: true }
});

Common Pitfalls

Pitfall 1: Forgetting 'use server' directive

// ❌ Bad - Missing directive
export async function createPost(formData: FormData) {
  await db.posts.create({ data: { title: formData.get('title') } });
}

// ✅ Good - Directive included
'use server';
export async function createPost(formData: FormData) {
  await db.posts.create({ data: { title: formData.get('title') } });
}

Pitfall 2: Not handling loading states

// ❌ Bad - No loading state
const { data } = useQuery({ queryKey: ['posts'], queryFn: fetchPosts });
return <div>{data.map(post => ...)}</div>; // Crashes before data loads

// ✅ Good - Proper loading handling
const { data, isLoading } = useQuery({ 
  queryKey: ['posts'], 
  queryFn: fetchPosts 
});
if (isLoading) return <LoadingSpinner />;
return <div>{data.map(post => ...)}</div>;

Pitfall 3: Incorrect query invalidation

// ❌ Bad - Too broad invalidation
queryClient.invalidateQueries(); // Refetches everything!

// ✅ Good - Targeted invalidation
queryClient.invalidateQueries({ queryKey: ['posts'] });

Conclusion

Mastering data fetching in Next.js 15 means understanding when to use each pattern: Server Actions for forms and mutations, Server Components for initial data loading, Route Handlers for external APIs, and React Query for complex client-side state management. Each approach has specific strengths, and combining them effectively creates applications that feel instant while maintaining data consistency.

The key takeaways: use Server Actions for progressive enhancement and seamless form handling, implement optimistic updates for immediate user feedback, leverage appropriate caching strategies for different data types, use React Query for complex client-side scenarios like polling and infinite scroll, and always handle errors gracefully with proper user feedback. These patterns form the foundation of modern, performant Next.js applications.

Remember that data fetching isn't just about getting data from point A to point B—it's about creating experiences that feel fast, reliable, and intuitive. Start with Server Components and Server Actions for simplicity, then add React Query when you need advanced client-side features. The architecture you build today determines how maintainable and scalable your application will be tomorrow.

Resources

GitHub Repository

Next.js Data Fetching Examples - Official examples

Official Documentation

Next.js Data Fetching - Comprehensive guide
Server Actions Documentation - Complete reference
Route Handlers Guide - API endpoints
TanStack Query Documentation - React Query complete guide

Related Articles

"Next.js 15 App Router: Complete Guide to Server and Client Components" - Component architecture fundamentals
"Next.js Caching Deep Dive: Request Memoization, Data Cache, and Full Route Cache" - Advanced caching strategies
"Building Real-Time Features in Next.js with Server Actions and WebSockets" - Real-time data patterns

Meta Description: Master Next.js 15 data fetching with Server Actions, API routes, and React Query. Complete guide to CRUD operations, optimistic updates, and caching strategies.

Tags: #nextjs #datafetching #serveractions #reactquery #typescript #crud #webdev

Mastering Next.js Routing: Dynamic Routes, Route Groups, and Parallel Routes

jordan wilfry — Sun, 11 Jan 2026 17:14:12 +0000

Unlocking the Full Power of Next.js 15's File-Based Routing System

Next.js has always been celebrated for its intuitive file-based routing, but the App Router in Next.js 15 takes this concept to unprecedented levels of sophistication. While the basics of creating a page by adding a file seem simple, developers often struggle with more advanced routing patterns: organizing complex applications with route groups, handling dynamic segments efficiently, implementing parallel routes for sophisticated layouts, and intercepting routes for modal experiences.

This comprehensive guide takes you from fundamental routing concepts to advanced patterns that power production applications. You'll learn how to structure your file system for optimal organization, create dynamic product pages that scale, build dashboard layouts with parallel data streams, implement modal interactions using intercepting routes, and master route handlers for API endpoints. Whether you're building a simple blog or a complex e-commerce platform, you'll gain the routing expertise needed to architect maintainable Next.js applications.

Prerequisites

Before exploring advanced routing patterns, ensure you have:

Next.js 15 installed - npx create-next-app@latest my-app
Basic Next.js App Router knowledge - Understanding of page.tsx and layout.tsx
TypeScript fundamentals - Interfaces, types, and basic syntax
React knowledge - Components, props, and basic hooks
File system concepts - Understanding folders, paths, and directory structures
HTTP methods - GET, POST, PUT, DELETE basics
Code editor - VS Code with Next.js snippets extension recommended

The Foundation: File-Based Routing Basics

Next.js uses your file system structure to define routes automatically. Each folder in the app directory represents a URL segment, and special files define the UI for that route.

Core Routing Files

app/
├── page.tsx              // Route: /
├── layout.tsx            // Applies to / and all children
├── loading.tsx           // Loading UI for /
├── error.tsx             // Error UI for /
├── not-found.tsx         // 404 UI for /
└── about/
    └── page.tsx          // Route: /about

Let's build a basic routing structure:

// app/page.tsx
export default function HomePage() {
  return (
    <div>
      <h1>Welcome to Our Store</h1>
      <p>Discover amazing products</p>
    </div>
  );
}

// app/layout.tsx
import { ReactNode } from 'react';
import './globals.css';

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        <nav>
          <a href="/">Home</a>
          <a href="/products">Products</a>
          <a href="/about">About</a>
        </nav>
        <main>{children}</main>
      </body>
    </html>
  );
}

Understanding Route Segments

Each folder creates a URL segment:

app/
├── blog/
│   ├── page.tsx          // /blog
│   └── authors/
│       └── page.tsx      // /blog/authors
└── products/
    ├── page.tsx          // /products
    └── categories/
        └── page.tsx      // /products/categories

Dynamic Routes: Building Scalable URL Patterns

Dynamic routes allow you to create pages for dynamic data without creating individual files for each item.

Single Dynamic Segment

Create a dynamic segment using square brackets:

app/
└── products/
    └── [id]/
        └── page.tsx      // Matches /products/1, /products/abc, etc.

// app/products/[id]/page.tsx
interface ProductPageProps {
  params: {
    id: string;
  };
}

async function getProduct(id: string) {
  const res = await fetch(`https://api.example.com/products/${id}`, {
    next: { revalidate: 3600 }
  });

  if (!res.ok) throw new Error('Failed to fetch product');
  return res.json();
}

export default async function ProductPage({ params }: ProductPageProps) {
  const product = await getProduct(params.id);

  return (
    <div className="product-container">
      <h1>{product.name}</h1>
      <img src={product.image} alt={product.name} />
      <p className="price">${product.price}</p>
      <p className="description">{product.description}</p>
      <button>Add to Cart</button>
    </div>
  );
}

Generating Static Params

For static generation with dynamic routes, use generateStaticParams:

// app/products/[id]/page.tsx
export async function generateStaticParams() {
  const products = await fetch('https://api.example.com/products').then(
    res => res.json()
  );

  return products.map((product: any) => ({
    id: product.id.toString(),
  }));
}

// This generates static pages at build time for all products
export default async function ProductPage({ params }: ProductPageProps) {
  const product = await getProduct(params.id);
  return <div>{product.name}</div>;
}

Multiple Dynamic Segments

Create complex URL patterns with multiple dynamic segments:

app/
└── blog/
    └── [category]/
        └── [slug]/
            └── page.tsx  // Matches /blog/tech/nextjs-guide

// app/blog/[category]/[slug]/page.tsx
interface BlogPostProps {
  params: {
    category: string;
    slug: string;
  };
}

export async function generateStaticParams() {
  const posts = await fetch('https://api.example.com/posts').then(
    res => res.json()
  );

  return posts.map((post: any) => ({
    category: post.category,
    slug: post.slug,
  }));
}

export default async function BlogPost({ params }: BlogPostProps) {
  const post = await fetch(
    `https://api.example.com/posts/${params.category}/${params.slug}`
  ).then(res => res.json());

  return (
    <article>
      <div className="breadcrumb">
        <a href="/blog">Blog</a> / 
        <a href={`/blog/${params.category}`}>{params.category}</a> / 
        <span>{post.title}</span>
      </div>
      <h1>{post.title}</h1>
      <div dangerouslySetInnerHTML={{ __html: post.content }} />
    </article>
  );
}

Catch-All Segments

Match multiple path segments with catch-all routes:

app/
└── shop/
    └── [...slug]/
        └── page.tsx      // Matches /shop/a, /shop/a/b, /shop/a/b/c

// app/shop/[...slug]/page.tsx
interface ShopPageProps {
  params: {
    slug: string[];  // Array of path segments
  };
}

export default async function ShopPage({ params }: ShopPageProps) {
  // /shop/electronics/phones/iphone -> ['electronics', 'phones', 'iphone']
  const { slug } = params;

  // Determine what to show based on depth
  if (slug.length === 1) {
    // Category page: /shop/electronics
    return <CategoryPage category={slug[0]} />;
  } else if (slug.length === 2) {
    // Subcategory page: /shop/electronics/phones
    return <SubcategoryPage category={slug[0]} subcategory={slug[1]} />;
  } else if (slug.length === 3) {
    // Product page: /shop/electronics/phones/iphone
    return <ProductDetailPage path={slug} />;
  }

  return <div>Shop</div>;
}

Optional Catch-All Segments

Match zero or more segments:

app/
└── docs/
    └── [[...slug]]/
        └── page.tsx      // Matches /docs, /docs/a, /docs/a/b

// app/docs/[[...slug]]/page.tsx
interface DocsPageProps {
  params: {
    slug?: string[];  // Optional array
  };
}

export default async function DocsPage({ params }: DocsPageProps) {
  const slug = params.slug || [];

  // /docs -> Show documentation home
  if (slug.length === 0) {
    return <DocsHome />;
  }

  // /docs/api/authentication -> Show specific doc
  const docPath = slug.join('/');
  const doc = await fetchDoc(docPath);

  return (
    <div className="docs-container">
      <aside>
        <DocsSidebar currentPath={docPath} />
      </aside>
      <article>
        <h1>{doc.title}</h1>
        <div dangerouslySetInnerHTML={{ __html: doc.content }} />
      </article>
    </div>
  );
}

Route Groups: Organizing Your Application

Route groups let you organize routes without affecting the URL structure. Create a route group by wrapping a folder name in parentheses.

Basic Route Groups

app/
├── (marketing)/
│   ├── about/
│   │   └── page.tsx      // URL: /about (not /marketing/about)
│   ├── contact/
│   │   └── page.tsx      // URL: /contact
│   └── layout.tsx        // Applies to marketing pages only
└── (shop)/
    ├── products/
    │   └── page.tsx      // URL: /products (not /shop/products)
    └── layout.tsx        // Applies to shop pages only

// app/(marketing)/layout.tsx
export default function MarketingLayout({ 
  children 
}: { 
  children: React.ReactNode 
}) {
  return (
    <div>
      <header className="marketing-header">
        <nav>
          <a href="/">Home</a>
          <a href="/about">About</a>
          <a href="/contact">Contact</a>
        </nav>
      </header>
      {children}
      <footer className="marketing-footer">
        <p>&copy; 2026 Our Company</p>
      </footer>
    </div>
  );
}

// app/(shop)/layout.tsx
export default function ShopLayout({ 
  children 
}: { 
  children: React.ReactNode 
}) {
  return (
    <div>
      <header className="shop-header">
        <nav>
          <a href="/products">Products</a>
          <a href="/cart">Cart</a>
          <a href="/account">Account</a>
        </nav>
      </header>
      <div className="shop-content">
        <aside className="shop-sidebar">
          <FilterPanel />
        </aside>
        <main>{children}</main>
      </div>
    </div>
  );
}

Multiple Root Layouts

Route groups enable multiple root layouts in your application:

app/
├── (auth)/
│   ├── layout.tsx        // Auth-specific root layout
│   ├── login/
│   │   └── page.tsx
│   └── register/
│       └── page.tsx
└── (dashboard)/
    ├── layout.tsx        // Dashboard-specific root layout
    ├── page.tsx
    └── settings/
        └── page.tsx

// app/(auth)/layout.tsx
export default function AuthLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body className="auth-body">
        <div className="auth-container">
          <div className="auth-card">
            {children}
          </div>
        </div>
      </body>
    </html>
  );
}

// app/(dashboard)/layout.tsx
export default function DashboardLayout({ 
  children 
}: { 
  children: React.ReactNode 
}) {
  return (
    <html lang="en">
      <body className="dashboard-body">
        <nav className="dashboard-nav">
          <a href="/dashboard">Dashboard</a>
          <a href="/dashboard/analytics">Analytics</a>
          <a href="/dashboard/settings">Settings</a>
        </nav>
        <main className="dashboard-main">
          {children}
        </main>
      </body>
    </html>
  );
}

Organizing by Feature

Use route groups to organize by feature while maintaining flat URLs:

app/
├── (products)/
│   ├── products/
│   │   └── page.tsx          // /products
│   ├── products/[id]/
│   │   └── page.tsx          // /products/[id]
│   └── categories/
│       └── page.tsx          // /categories
└── (users)/
    ├── profile/
    │   └── page.tsx          // /profile
    └── settings/
        └── page.tsx          // /settings

Parallel Routes: Loading Multiple Pages Simultaneously

Parallel routes allow you to render multiple pages in the same layout simultaneously, each with independent loading and error states.

Creating Parallel Routes

Define parallel routes using the @folder convention:

app/
└── dashboard/
    ├── @analytics/
    │   ├── page.tsx
    │   └── loading.tsx
    ├── @notifications/
    │   ├── page.tsx
    │   └── loading.tsx
    ├── layout.tsx
    └── page.tsx

// app/dashboard/layout.tsx
export default function DashboardLayout({
  children,
  analytics,
  notifications,
}: {
  children: React.ReactNode;
  analytics: React.ReactNode;
  notifications: React.ReactNode;
}) {
  return (
    <div className="dashboard-grid">
      <div className="dashboard-main">
        {children}
      </div>
      <div className="dashboard-analytics">
        {analytics}
      </div>
      <div className="dashboard-notifications">
        {notifications}
      </div>
    </div>
  );
}

// app/dashboard/@analytics/page.tsx
async function getAnalytics() {
  const res = await fetch('https://api.example.com/analytics', {
    next: { revalidate: 300 }  // Revalidate every 5 minutes
  });
  return res.json();
}

export default async function AnalyticsSlot() {
  const data = await getAnalytics();

  return (
    <div className="analytics-panel">
      <h2>Analytics</h2>
      <div className="metrics">
        <div className="metric">
          <span className="metric-label">Page Views</span>
          <span className="metric-value">{data.pageViews}</span>
        </div>
        <div className="metric">
          <span className="metric-label">Users</span>
          <span className="metric-value">{data.users}</span>
        </div>
      </div>
    </div>
  );
}

// app/dashboard/@analytics/loading.tsx
export default function AnalyticsLoading() {
  return (
    <div className="analytics-panel">
      <h2>Analytics</h2>
      <div className="loading-skeleton">
        <div className="skeleton-line"></div>
        <div className="skeleton-line"></div>
      </div>
    </div>
  );
}

Conditional Rendering with Parallel Routes

Show different content based on user state:

// app/dashboard/layout.tsx
import { getUser } from '@/lib/auth';

export default async function DashboardLayout({
  children,
  analytics,
  team,
}: {
  children: React.ReactNode;
  analytics: React.ReactNode;
  team: React.ReactNode;
}) {
  const user = await getUser();

  return (
    <div className="dashboard">
      {children}
      {analytics}
      {user.role === 'admin' && team}
    </div>
  );
}

Default Parallel Routes

Provide a default when no matching page exists:

app/
└── dashboard/
    ├── @analytics/
    │   ├── default.tsx       // Fallback for @analytics
    │   └── page.tsx
    └── layout.tsx

// app/dashboard/@analytics/default.tsx
export default function AnalyticsDefault() {
  return (
    <div className="analytics-panel">
      <p>Analytics not available for this view</p>
    </div>
  );
}

Intercepting Routes: Creating Modal Experiences

Intercepting routes allow you to load a route within the current layout while still preserving the URL for sharing and refreshing.

Intercepting Route Conventions

(.) - Match segments on the same level
(..) - Match segments one level above
(..)(..) - Match segments two levels above
(...) - Match segments from the root

Building a Photo Gallery with Modals

app/
└── photos/
    ├── page.tsx              // Gallery view
    ├── [id]/
    │   └── page.tsx          // Full photo page
    └── (.)[id]/
        └── page.tsx          // Intercepted modal view

// app/photos/page.tsx
import Link from 'next/link';

async function getPhotos() {
  const res = await fetch('https://api.example.com/photos');
  return res.json();
}

export default async function PhotosPage() {
  const photos = await getPhotos();

  return (
    <div className="photo-grid">
      {photos.map((photo: any) => (
        <Link key={photo.id} href={`/photos/${photo.id}`}>
          <img src={photo.thumbnail} alt={photo.title} />
        </Link>
      ))}
    </div>
  );
}

// app/photos/(.)[id]/page.tsx - Modal view
import { Modal } from '@/components/Modal';

async function getPhoto(id: string) {
  const res = await fetch(`https://api.example.com/photos/${id}`);
  return res.json();
}

export default async function PhotoModal({ 
  params 
}: { 
  params: { id: string } 
}) {
  const photo = await getPhoto(params.id);

  return (
    <Modal>
      <img src={photo.url} alt={photo.title} className="modal-image" />
      <h2>{photo.title}</h2>
      <p>{photo.description}</p>
    </Modal>
  );
}

// app/photos/[id]/page.tsx - Full page view
async function getPhoto(id: string) {
  const res = await fetch(`https://api.example.com/photos/${id}`);
  return res.json();
}

export default async function PhotoPage({ 
  params 
}: { 
  params: { id: string } 
}) {
  const photo = await getPhoto(params.id);

  return (
    <div className="photo-page">
      <img src={photo.url} alt={photo.title} />
      <div className="photo-details">
        <h1>{photo.title}</h1>
        <p>{photo.description}</p>
        <div className="photo-meta">
          <span>Uploaded: {photo.uploadDate}</span>
          <span>Views: {photo.views}</span>
        </div>
      </div>
    </div>
  );
}

// components/Modal.tsx
'use client';

import { useRouter } from 'next/navigation';
import { useEffect, useRef } from 'react';

export function Modal({ children }: { children: React.ReactNode }) {
  const router = useRouter();
  const dialogRef = useRef<HTMLDialogElement>(null);

  useEffect(() => {
    dialogRef.current?.showModal();
  }, []);

  const handleClose = () => {
    router.back();
  };

  return (
    <dialog ref={dialogRef} onClose={handleClose} className="photo-modal">
      <button onClick={handleClose} className="close-button">×</button>
      {children}
    </dialog>
  );
}

E-commerce Product Quick View

app/
└── products/
    ├── page.tsx              // Product listing
    ├── [id]/
    │   └── page.tsx          // Full product page
    └── (.)[id]/
        └── page.tsx          // Quick view modal

// app/products/(.)[id]/page.tsx
import { Modal } from '@/components/Modal';
import { AddToCartButton } from '@/components/AddToCartButton';

async function getProduct(id: string) {
  const res = await fetch(`https://api.example.com/products/${id}`);
  return res.json();
}

export default async function ProductQuickView({ 
  params 
}: { 
  params: { id: string } 
}) {
  const product = await getProduct(params.id);

  return (
    <Modal>
      <div className="quick-view">
        <div className="quick-view-image">
          <img src={product.image} alt={product.name} />
        </div>
        <div className="quick-view-details">
          <h2>{product.name}</h2>
          <p className="price">${product.price}</p>
          <p className="description">{product.shortDescription}</p>
          <AddToCartButton productId={product.id} />
          <a href={`/products/${product.id}`} className="view-full">
            View Full Details →
          </a>
        </div>
      </div>
    </Modal>
  );
}

Route Handlers: Building API Endpoints

Route handlers allow you to create custom API endpoints using Web Request and Response APIs.

Basic Route Handler

// app/api/products/route.ts
import { NextRequest, NextResponse } from 'next/server';

export async function GET(request: NextRequest) {
  const products = await fetchProducts();

  return NextResponse.json({
    success: true,
    data: products,
  });
}

export async function POST(request: NextRequest) {
  const body = await request.json();

  const newProduct = await createProduct(body);

  return NextResponse.json({
    success: true,
    data: newProduct,
  }, { status: 201 });
}

Dynamic Route Handlers

// app/api/products/[id]/route.ts
import { NextRequest, NextResponse } from 'next/server';

interface RouteParams {
  params: {
    id: string;
  };
}

export async function GET(
  request: NextRequest,
  { params }: RouteParams
) {
  const product = await fetchProduct(params.id);

  if (!product) {
    return NextResponse.json(
      { success: false, error: 'Product not found' },
      { status: 404 }
    );
  }

  return NextResponse.json({
    success: true,
    data: product,
  });
}

export async function PATCH(
  request: NextRequest,
  { params }: RouteParams
) {
  const body = await request.json();
  const updatedProduct = await updateProduct(params.id, body);

  return NextResponse.json({
    success: true,
    data: updatedProduct,
  });
}

export async function DELETE(
  request: NextRequest,
  { params }: RouteParams
) {
  await deleteProduct(params.id);

  return NextResponse.json({
    success: true,
    message: 'Product deleted',
  });
}

Accessing Request Data

// app/api/search/route.ts
import { NextRequest, NextResponse } from 'next/server';

export async function GET(request: NextRequest) {
  // Get query parameters
  const searchParams = request.nextUrl.searchParams;
  const query = searchParams.get('q');
  const page = searchParams.get('page') || '1';
  const limit = searchParams.get('limit') || '10';

  // Get headers
  const authToken = request.headers.get('authorization');

  // Get cookies
  const cookies = request.cookies;
  const sessionId = cookies.get('sessionId')?.value;

  if (!authToken) {
    return NextResponse.json(
      { error: 'Unauthorized' },
      { status: 401 }
    );
  }

  const results = await searchProducts({
    query,
    page: parseInt(page),
    limit: parseInt(limit),
  });

  return NextResponse.json({
    success: true,
    data: results,
    pagination: {
      page: parseInt(page),
      limit: parseInt(limit),
      total: results.total,
    },
  });
}

Setting Response Headers and Cookies

// app/api/login/route.ts
import { NextRequest, NextResponse } from 'next/server';

export async function POST(request: NextRequest) {
  const { email, password } = await request.json();

  const user = await authenticateUser(email, password);

  if (!user) {
    return NextResponse.json(
      { error: 'Invalid credentials' },
      { status: 401 }
    );
  }

  const token = generateToken(user);

  const response = NextResponse.json({
    success: true,
    user: {
      id: user.id,
      email: user.email,
      name: user.name,
    },
  });

  // Set cookie
  response.cookies.set('token', token, {
    httpOnly: true,
    secure: process.env.NODE_ENV === 'production',
    sameSite: 'lax',
    maxAge: 60 * 60 * 24 * 7, // 7 days
  });

  // Set custom headers
  response.headers.set('X-User-Id', user.id);

  return response;
}

Streaming Responses

// app/api/stream/route.ts
export async function GET() {
  const encoder = new TextEncoder();

  const stream = new ReadableStream({
    async start(controller) {
      for (let i = 0; i < 10; i++) {
        await new Promise(resolve => setTimeout(resolve, 1000));
        controller.enqueue(encoder.encode(`data: Message ${i}\n\n`));
      }
      controller.close();
    },
  });

  return new Response(stream, {
    headers: {
      'Content-Type': 'text/event-stream',
      'Cache-Control': 'no-cache',
      'Connection': 'keep-alive',
    },
  });
}

Best Practices Section

✅ Dos

Use route groups for organization - Keep your file structure clean and maintainable without affecting URLs:

// ✅ Good - Organized by feature
app/
├── (auth)/
│   ├── login/
│   └── register/
└── (dashboard)/
    ├── analytics/
    └── settings/

Leverage generateStaticParams for dynamic routes - Pre-render pages at build time for better performance:

// ✅ Good - Static generation
export async function generateStaticParams() {
  const posts = await fetchAllPosts();
  return posts.map(post => ({ slug: post.slug }));
}

Implement proper loading and error states - Use loading.tsx and error.tsx files for better UX:

// app/products/loading.tsx
export default function Loading() {
  return <ProductGridSkeleton />;
}

// app/products/error.tsx
'use client';
export default function Error({ error, reset }: {
  error: Error;
  reset: () => void;
}) {
  return (
    <div>
      <h2>Something went wrong!</h2>
      <button onClick={reset}>Try again</button>
    </div>
  );
}

Use intercepting routes for modal experiences - Preserve URLs while showing modals for better sharing and navigation:

// ✅ Good - Modal with shareable URL
app/
└── photos/
    ├── [id]/page.tsx         // Full page
    └── (.)[id]/page.tsx      // Modal intercept

Validate and sanitize route handler inputs - Always validate incoming data:

// ✅ Good - Input validation
export async function POST(request: NextRequest) {
  const body = await request.json();

  if (!body.email || !isValidEmail(body.email)) {
    return NextResponse.json(
      { error: 'Invalid email' },
      { status: 400 }
    );
  }

  // Process valid data
}

❌ Don'ts

Don't create unnecessary nesting - Keep routes as flat as possible:

// ❌ Bad - Too nested
app/pages/products/categories/electronics/page.tsx

// ✅ Good - Flatter structure
app/categories/[slug]/page.tsx

Don't forget to handle errors in route handlers - Always include error handling:

// ❌ Bad - No error handling
export async function GET() {
  const data = await fetchData(); // Can throw
  return NextResponse.json(data);
}

// ✅ Good - Proper error handling
export async function GET() {
  try {
    const data = await fetchData();
    return NextResponse.json({ success: true, data });
  } catch (error) {
    console.error('API Error:', error);
    return NextResponse.json(
      { success: false, error: 'Internal server error' },
      { status: 500 }
    );
  }
}

Don't use route handlers for server-side rendering - Use Server Components instead:

// ❌ Bad - Using API route for data
'use client';
export default function Page() {
  const [data, setData] = useState(null);
  useEffect(() => {
    fetch('/api/data').then(r => r.json()).then(setData);
  }, []);
  return <div>{data?.title}</div>;
}

// ✅ Good - Server Component
export default async function Page() {
  const data = await fetchData();
  return <div>{data.title}</div>;
}

Don't expose sensitive data in parallel routes - Remember all slots are exposed to the client:

// ❌ Bad - Sensitive data in parallel route
app/dashboard/@admin/page.tsx  // Admin data visible to all users

// ✅ Good - Check permissions in layout
export default async function Layout({ admin }) {
  const user = await getUser();
  return user.isAdmin ? admin : null;
}

Common Pitfalls

Pitfall 1: Forgetting default.tsx for parallel routes

When navigating to a route that doesn't have a matching parallel route page, Next.js needs a fallback:

// ❌ Bad - Missing default
app/dashboard/
├── @analytics/page.tsx
└── layout.tsx

// Navigate to /dashboard/settings -> Error!

// ✅ Good - Include default
app/dashboard/
├── @analytics/
│   ├── page.tsx
│   └── default.tsx           // Fallback
└── layout.tsx

Pitfall 2: Incorrect intercepting route conventions

// ❌ Bad - Wrong intercept level
app/photos/
└── (..)[id]/page.tsx         // Goes up one level, not same level

// ✅ Good - Same level intercept
app/photos/
└── (.)[id]/page.tsx          // Correct for same level

Pitfall
3: Not handling the back button in modals

// ❌ Bad - No back button handling
export function Modal({ children }) {
  return <div className="modal">{children}</div>;
}

// ✅ Good - Proper router integration
'use client';
import { useRouter } from 'next/navigation';

export function Modal({ children }) {
  const router = useRouter();
  return (
    <div className="modal" onClick={() => router.back()}>
      {children}
    </div>
  );
}

Conclusion

Mastering Next.js routing unlocks the full potential of the App Router architecture. From basic file-based routing to advanced patterns like parallel and intercepting routes, you now have the knowledge to build sophisticated, scalable applications with clean and maintainable code structures.

The key takeaways: use dynamic routes with generateStaticParams for optimal performance, organize complex applications with route groups without affecting URLs, leverage parallel routes for loading multiple data sources simultaneously, implement intercepting routes for seamless modal experiences, and create robust API endpoints with route handlers. Each pattern serves specific use cases, and choosing the right combination makes the difference between a good application and a great one.

Remember that routing is not just about URLs—it's about creating intuitive user experiences, organizing your codebase effectively, and optimizing performance. Start with simple patterns and gradually incorporate advanced techniques as your application grows. The file-based routing system may seem magical at first, but understanding these patterns gives you complete control over how your application behaves.

Resources

GitHub Repository

Next.js Routing Examples - Official routing examples

Official Documentation

Next.js Routing Fundamentals - Comprehensive routing guide
Route Handlers Documentation - API endpoints reference
Parallel Routes Guide - Advanced parallel routing

Related Articles

"Next.js 15 App Router: Complete Guide to Server and Client Components" - Understand component architecture
"Building Authentication Systems in Next.js with Route Protection" - Secure your routes
"Next.js Middleware: Advanced Request Handling and Route Protection" - Route-level logic

Meta Description: Master Next.js 15 routing with dynamic routes, route groups, parallel routes, and intercepting routes. Complete guide with e-commerce examples and best practices.

Tags: #nextjs #routing #webdev #react #typescript #apirouter #tutorial

Next.js 15 App Router: Complete Guide to Server and Client Components

jordan wilfry — Sat, 10 Jan 2026 18:19:42 +0000

Understanding the Revolutionary Shift in React Architecture

The Next.js 15 App Router introduces a paradigm shift in how we build React applications. With React Server Components (RSC) at its core, developers now face a fundamentally different mental model compared to the traditional client-side rendering approach. Many intermediate developers find themselves confused about when to use server components versus client components, how hydration works in this new architecture, and what rendering strategies to employ for optimal performance.

This comprehensive guide demystifies Server and Client Components in Next.js 15. You'll learn the architectural differences between these component types, understand the hydration process, master various rendering strategies, and discover practical patterns for data fetching. By the end, you'll confidently architect Next.js applications that leverage the full power of the App Router while avoiding common pitfalls.

Prerequisites

Before diving into this guide, ensure you have:

Solid understanding of React fundamentals - hooks, props, state management
Basic Next.js experience - familiarity with file-based routing
JavaScript ES6+ knowledge - async/await, destructuring, modules
Node.js 18.17 or later installed on your machine
npm, yarn, or pnpm package manager
Code editor with TypeScript support (VS Code recommended)
Basic understanding of HTTP - requests, responses, status codes

The Foundation: Understanding React Server Components

React Server Components represent a fundamental rethinking of how React applications render content. Unlike traditional React components that execute entirely in the browser, Server Components run exclusively on the server during the build process or at request time.

What Makes Server Components Different?

Server Components never ship JavaScript to the client. This means:

// app/products/page.tsx
// This is a Server Component by default in the App Router
async function ProductsPage() {
  // Direct database access - no API route needed!
  const products = await db.query('SELECT * FROM products');

  return (
    <div>
      <h1>Our Products</h1>
      {products.map(product => (
        <ProductCard key={product.id} product={product} />
      ))}
    </div>
  );
}

export default ProductsPage;

This component runs on the server, fetches data directly from the database, and sends only the rendered HTML to the client. The entire db.query logic never reaches the browser, keeping your database credentials and business logic secure.

The Client Component Boundary

Client Components are designated with the 'use client' directive and behave like traditional React components:

// components/AddToCartButton.tsx
'use client';

import { useState } from 'react';

export function AddToCartButton({ productId }: { productId: string }) {
  const [isLoading, setIsLoading] = useState(false);

  const handleClick = async () => {
    setIsLoading(true);
    try {
      await fetch('/api/cart', {
        method: 'POST',
        body: JSON.stringify({ productId }),
      });
    } finally {
      setIsLoading(false);
    }
  };

  return (
    <button onClick={handleClick} disabled={isLoading}>
      {isLoading ? 'Adding...' : 'Add to Cart'}
    </button>
  );
}

This component needs interactivity (state and event handlers), so it must be a Client Component. The 'use client' directive marks the boundary where client-side JavaScript begins.

Component Composition Patterns

Understanding how to compose Server and Client Components is crucial for building efficient applications.

Pattern 1: Server Component with Client Component Children

The most common pattern involves a Server Component that fetches data and renders Client Components:

// app/dashboard/page.tsx (Server Component)
import { AnalyticsChart } from '@/components/AnalyticsChart';
import { getUserAnalytics } from '@/lib/analytics';

async function DashboardPage() {
  const analytics = await getUserAnalytics();

  return (
    <div>
      <h1>Dashboard</h1>
      {/* Pass data from server to client component */}
      <AnalyticsChart data={analytics} />
    </div>
  );
}

export default DashboardPage;

// components/AnalyticsChart.tsx (Client Component)
'use client';

import { LineChart } from 'recharts';
import { useState } from 'react';

export function AnalyticsChart({ data }: { data: any[] }) {
  const [filter, setFilter] = useState('week');

  const filteredData = data.filter(/* filter logic */);

  return (
    <div>
      <select value={filter} onChange={e => setFilter(e.target.value)}>
        <option value="week">This Week</option>
        <option value="month">This Month</option>
      </select>
      <LineChart data={filteredData} />
    </div>
  );
}

Pattern 2: Passing Server Components as Props

You can pass Server Components as children or props to Client Components:

// components/ClientWrapper.tsx
'use client';

import { ReactNode } from 'react';

export function ClientWrapper({ children }: { children: ReactNode }) {
  return (
    <div className="animated-wrapper">
      {children}
    </div>
  );
}

// app/page.tsx (Server Component)
import { ClientWrapper } from '@/components/ClientWrapper';

async function HomePage() {
  const posts = await fetchPosts();

  return (
    <ClientWrapper>
      {/* This remains a Server Component! */}
      <PostList posts={posts} />
    </ClientWrapper>
  );
}

This pattern allows the PostList to remain a Server Component even though it's rendered inside a Client Component boundary.

Pattern 3: The Context Provider Pattern

When you need to share client-side state across your application:

// providers/ThemeProvider.tsx
'use client';

import { createContext, useContext, useState, ReactNode } from 'react';

const ThemeContext = createContext<{
  theme: string;
  setTheme: (theme: string) => void;
}>({ theme: 'light', setTheme: () => {} });

export function ThemeProvider({ children }: { children: ReactNode }) {
  const [theme, setTheme] = useState('light');

  return (
    <ThemeContext.Provider value={{ theme, setTheme }}>
      {children}
    </ThemeContext.Provider>
  );
}

export const useTheme = () => useContext(ThemeContext);

// app/layout.tsx (Server Component)
import { ThemeProvider } from '@/providers/ThemeProvider';

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html>
      <body>
        <ThemeProvider>
          {children}
        </ThemeProvider>
      </body>
    </html>
  );
}

Understanding Hydration in the App Router

Hydration is the process where React attaches event listeners and state to server-rendered HTML, making it interactive. In Next.js 15, hydration only occurs for Client Components.

The Hydration Process Explained

// app/article/[id]/page.tsx
import { ArticleContent } from '@/components/ArticleContent';
import { CommentSection } from '@/components/CommentSection';

async function ArticlePage({ params }: { params: { id: string } }) {
  // Fetched on the server
  const article = await fetchArticle(params.id);

  return (
    <article>
      {/* Server Component - no hydration needed */}
      <ArticleContent content={article.content} />

      {/* Client Component - will be hydrated */}
      <CommentSection articleId={params.id} />
    </article>
  );
}

When this page loads:

Initial HTML - Server generates complete HTML including both components
JavaScript Download - Browser downloads only the JS for CommentSection
Hydration - React attaches interactivity to CommentSection
Result - ArticleContent remains static HTML, CommentSection is fully interactive

Avoiding Hydration Mismatches

A common pitfall is creating content on the server that differs from what the client expects:

// ❌ WRONG - Will cause hydration mismatch
'use client';

export function DateDisplay() {
  return <div>Current time: {new Date().toISOString()}</div>;
}

The server and client will generate different timestamps, causing a mismatch. The solution:

// ✅ CORRECT - Render after hydration
'use client';

import { useState, useEffect } from 'react';

export function DateDisplay() {
  const [date, setDate] = useState<string | null>(null);

  useEffect(() => {
    setDate(new Date().toISOString());
  }, []);

  if (!date) return <div>Loading time...</div>;

  return <div>Current time: {date}</div>;
}

Rendering Strategies in Next.js 15

Next.js 15 offers multiple rendering strategies, each optimized for different use cases.

Static Rendering (Default)

By default, all routes are statically rendered at build time:

// app/blog/page.tsx
async function BlogPage() {
  const posts = await fetchPosts();

  return (
    <div>
      {posts.map(post => (
        <BlogPostCard key={post.id} post={post} />
      ))}
    </div>
  );
}

export default BlogPage;

This page is rendered once during npm run build and served as static HTML. Perfect for content that doesn't change frequently.

Dynamic Rendering

Use dynamic functions to opt into dynamic rendering:

// app/dashboard/page.tsx
import { cookies } from 'next/headers';

async function DashboardPage() {
  // This makes the route dynamic
  const cookieStore = cookies();
  const userId = cookieStore.get('userId')?.value;

  const userData = await fetchUserData(userId);

  return <div>Welcome, {userData.name}!</div>;
}

Dynamic functions include: cookies(), headers(), searchParams, and unstable_noStore().

Incremental Static Regeneration (ISR)

Revalidate static pages after a specified time:

// app/products/page.tsx
async function ProductsPage() {
  const products = await fetch('https://api.example.com/products', {
    next: { revalidate: 3600 } // Revalidate every hour
  });

  return (
    <div>
      {products.map(product => (
        <ProductCard key={product.id} product={product} />
      ))}
    </div>
  );
}

Or use route segment config:

// app/blog/[slug]/page.tsx
export const revalidate = 3600; // Revalidate every hour

async function BlogPost({ params }: { params: { slug: string } }) {
  const post = await fetchPost(params.slug);
  return <article>{post.content}</article>;
}

On-Demand Revalidation

Trigger revalidation programmatically using tags:

// app/posts/[id]/page.tsx
async function PostPage({ params }: { params: { id: string } }) {
  const post = await fetch(`https://api.example.com/posts/${params.id}`, {
    next: { tags: [`post-${params.id}`] }
  });

  return <article>{post.content}</article>;
}

// app/api/revalidate/route.ts
import { revalidateTag } from 'next/cache';
import { NextRequest } from 'next/server';

export async function POST(request: NextRequest) {
  const { tag } = await request.json();
  revalidateTag(tag);
  return Response.json({ revalidated: true, now: Date.now() });
}

Advanced Data Fetching Patterns

Parallel Data Fetching

Fetch multiple data sources simultaneously:

// app/dashboard/page.tsx
async function DashboardPage() {
  // These fetch in parallel
  const [user, stats, notifications] = await Promise.all([
    fetchUser(),
    fetchStats(),
    fetchNotifications()
  ]);

  return (
    <div>
      <UserProfile user={user} />
      <StatsPanel stats={stats} />
      <NotificationsList notifications={notifications} />
    </div>
  );
}

Sequential Data Fetching

When one fetch depends on another:

// app/user/[id]/posts/page.tsx
async function UserPostsPage({ params }: { params: { id: string } }) {
  // Fetch user first
  const user = await fetchUser(params.id);

  // Then fetch their posts
  const posts = await fetchUserPosts(user.email);

  return (
    <div>
      <h1>{user.name}'s Posts</h1>
      <PostList posts={posts} />
    </div>
  );
}

Streaming with Suspense

Show content progressively as it loads:

// app/dashboard/page.tsx
import { Suspense } from 'react';

function DashboardPage() {
  return (
    <div>
      <h1>Dashboard</h1>

      {/* Shows immediately */}
      <QuickStats />

      {/* Shows loading state, then content */}
      <Suspense fallback={<AnalyticsLoading />}>
        <AnalyticsPanel />
      </Suspense>

      <Suspense fallback={<RecentActivityLoading />}>
        <RecentActivity />
      </Suspense>
    </div>
  );
}

async function AnalyticsPanel() {
  // Slow data fetch
  const analytics = await fetchAnalytics();
  return <div>{/* Render analytics */}</div>;
}

Request Memoization

Next.js automatically deduplicates requests made with the same URL and options:

// lib/data.ts
async function getUser() {
  return fetch('https://api.example.com/user', {
    next: { revalidate: 3600 }
  });
}

// app/layout.tsx
async function RootLayout() {
  const user = await getUser(); // First call
  return <header>{user.name}</header>;
}

// app/page.tsx
async function HomePage() {
  const user = await getUser(); // Deduplicated - uses cached result
  return <main>Welcome {user.name}</main>;
}

Best Practices Section

✅ Dos

Use Server Components by default - Only add 'use client' when you need interactivity, state, or browser APIs. This minimizes your JavaScript bundle size and improves performance.

Fetch data close to where it's used - Server Components allow you to colocate data fetching with the components that need it, improving maintainability:

// ✅ Good
async function ProductList() {
  const products = await fetchProducts();
  return products.map(p => <ProductCard key={p.id} product={p} />);
}

Keep Client Components small and focused - Extract only the interactive parts into Client Components:

// ✅ Good - Small client component
'use client';
export function LikeButton({ postId }: { postId: string }) {
  const [liked, setLiked] = useState(false);
  return <button onClick={() => setLiked(!liked)}>Like</button>;
}

// Server component uses it
async function BlogPost({ id }: { id: string }) {
  const post = await fetchPost(id);
  return (
    <article>
      <h1>{post.title}</h1>
      <p>{post.content}</p>
      <LikeButton postId={id} />
    </article>
  );
}

Use loading.tsx and error.tsx - Leverage Next.js file conventions for better UX:

// app/dashboard/loading.tsx
export default function Loading() {
  return <DashboardSkeleton />;
}

// app/dashboard/error.tsx
'use client';
export default function Error({ error, reset }: { error: Error; reset: () => void }) {
  return (
    <div>
      <h2>Something went wrong!</h2>
      <button onClick={reset}>Try again</button>
    </div>
  );
}

❌ Don'ts

Don't use 'use client' in layouts unnecessarily - This makes all child routes client-side:

// ❌ Bad - Makes entire app client-side
'use client';
export default function RootLayout({ children }) {
  return <html><body>{children}</body></html>;
}

Don't fetch data in Client Components when it can be done server-side - Exposes API keys and increases client-side bundle:

// ❌ Bad
'use client';
export function UserProfile() {
  const [user, setUser] = useState(null);
  useEffect(() => {
    fetch('/api/user').then(r => r.json()).then(setUser);
  }, []);
  return <div>{user?.name}</div>;
}

// ✅ Good
async function UserProfile() {
  const user = await fetchUser();
  return <div>{user.name}</div>;
}

Don't pass non-serializable props from Server to Client Components - Functions, dates, and class instances can't be passed:

// ❌ Bad
<ClientComponent 
  onClick={() => console.log('click')} 
  date={new Date()} 
/>

// ✅ Good
<ClientComponent 
  onClickAction="log-click"
  dateString={new Date().toISOString()} 
/>

Common Pitfalls

Pitfall 1: Import Order Violations

// ❌ This will error
'use client';
import ServerComponent from './ServerComponent'; // Server Component

// ✅ Pass as children instead
export function ClientComponent({ children }) {
  return <div>{children}</div>;
}

Pitfall 2: Forgetting async/await

// ❌ Bad - Missing await
async function Page() {
  const data = fetch('https://api.example.com/data');
  return <div>{data.title}</div>; // data is a Promise!
}

// ✅ Good
async function Page() {
  const data = await fetch('https://api.example.com/data');
  return <div>{data.title}</div>;
}

Pitfall 3: Using client hooks in Server Components

// ❌ Bad - useState in Server Component
import { useState } from 'react';

async function ServerComponent() {
  const [count, setCount] = useState(0); // Error!
  return <div>{count}</div>;
}

Conclusion

The Next.js 15 App Router with React Server Components represents a significant evolution in how we build React applications. By defaulting to Server Components and strategically introducing Client Components only where interactivity is needed, you can build applications that are faster, more secure, and easier to maintain.

Remember the key principles: Server Components for data fetching and static content, Client Components for interactivity, and thoughtful composition patterns to connect them. Master the different rendering strategies—static, dynamic, and ISR—to optimize for your specific use case. With Suspense streaming and proper error boundaries, you can create resilient applications that provide excellent user experiences even during loading states.

The mental shift from traditional client-side React takes time, but the benefits in performance, security, and developer experience make it worthwhile. Start by building small features with these patterns, and gradually expand your understanding as you encounter more complex scenarios.

Resources

GitHub Repository

Next.js App Router Examples - Official examples from Vercel

Official Documentation

Next.js 15 Documentation - Complete App Router reference
React Server Components - React team's explanation
Next.js Data Fetching - Official data fetching guide

Related Articles

"Optimizing Next.js 15 Performance: Caching Strategies and Best Practices"
"Building Real-Time Features in Next.js with Server Actions"
"Next.js Authentication Patterns: Server Components Edition"

Meta Description: Master Next.js 15 App Router with this complete guide to Server and Client Components. Learn RSC, hydration, rendering strategies, and data fetching patterns.

Tags: #nextjs #react #typescript #webdev #javascript #servercomponents #tutorial

Building Type-Safe APIs: Integrating NestJS with Prisma and TypeScript

jordan wilfry — Tue, 07 Jan 2025 12:10:05 +0000

As a full-stack developer, type safety has become increasingly crucial in building robust and maintainable applications. In this comprehensive guide, we'll explore how to create a fully type-safe API using NestJS, Prisma, and TypeScript. By the end, you'll have a solid understanding of how to build APIs that catch errors at compile-time rather than runtime.

🎯 What We'll Cover

Setting up a NestJS project with TypeScript
Integrating Prisma with NestJS
Creating type-safe database models
Implementing CRUD operations with full type safety
Best practices for error handling
Advanced TypeScript features for better type safety

Prerequisites

Node.js (v18 or later)
Basic understanding of TypeScript
Familiarity with RESTful APIs
PostgreSQL installed locally

Initial Setup

First, let's create a new NestJS project with TypeScript:

npm i -g @nestjs/cli
nest new type-safe-api
cd type-safe-api

Now, let's add Prisma to our project:

npm install @prisma/client
npm install prisma --save-dev
npx prisma init

Defining Our Schema

Let's create a simple blog API with posts and categories. Here's our Prisma schema:

// prisma/schema.prisma

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

model Post {
  id        Int      @id @default(autoincrement())
  title     String
  content   String
  published Boolean  @default(false)
  category  Category @relation(fields: [categoryId], references: [id])
  categoryId Int
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

model Category {
  id    Int     @id @default(autoincrement())
  name  String  @unique
  posts Post[]
}

Creating Type-Safe DTOs

One of the key benefits of using NestJS with TypeScript is the ability to create type-safe DTOs:

// src/posts/dto/create-post.dto.ts

import { IsString, IsBoolean, IsNumber, IsOptional } from 'class-validator';

export class CreatePostDto {
  @IsString()
  title: string;

  @IsString()
  content: string;

  @IsBoolean()
  @IsOptional()
  published?: boolean;

  @IsNumber()
  categoryId: number;
}

Implementing the Posts Service

Here's how we can implement a type-safe service layer:

// src/posts/posts.service.ts

import { Injectable, NotFoundException } from '@nestjs/common';
import { PrismaService } from '../prisma/prisma.service';
import { Post, Prisma } from '@prisma/client';
import { CreatePostDto } from './dto/create-post.dto';

@Injectable()
export class PostsService {
  constructor(private prisma: PrismaService) {}

  async create(data: CreatePostDto): Promise<Post> {
    return this.prisma.post.create({
      data: {
        ...data,
        published: data.published ?? false,
      },
      include: {
        category: true,
      },
    });
  }

  async findOne(id: number): Promise<Post> {
    const post = await this.prisma.post.findUnique({
      where: { id },
      include: {
        category: true,
      },
    });

    if (!post) {
      throw new NotFoundException(`Post with ID ${id} not found`);
    }

    return post;
  }
}

Error Handling with Type Safety

Let's implement a custom error handling mechanism that leverages TypeScript's type system:

// src/common/errors/api-error.ts

export class ApiError extends Error {
  constructor(
    public readonly code: string,
    public readonly message: string,
    public readonly status: number = 400,
    public readonly details?: Record<string, unknown>
  ) {
    super(message);
    this.name = 'ApiError';
  }

  static notFound(resource: string, id: number | string): ApiError {
    return new ApiError(
      'NOT_FOUND',
      `${resource} with ID ${id} not found`,
      404
    );
  }
}

Implementing Controllers with Type Safety

Here's how we can implement a type-safe controller:

// src/posts/posts.controller.ts

import { Controller, Get, Post, Body, Param, ParseIntPipe } from '@nestjs/common';
import { PostsService } from './posts.service';
import { CreatePostDto } from './dto/create-post.dto';

@Controller('posts')
export class PostsController {
  constructor(private readonly postsService: PostsService) {}

  @Post()
  create(@Body() createPostDto: CreatePostDto) {
    return this.postsService.create(createPostDto);
  }

  @Get(':id')
  findOne(@Param('id', ParseIntPipe) id: number) {
    return this.postsService.findOne(id);
  }
}

Advanced Type Safety Features

1. Custom Type Guards

// src/common/guards/type-guards.ts

export function isPost(obj: unknown): obj is Post {
  return (
    typeof obj === 'object' &&
    obj !== null &&
    'id' in obj &&
    'title' in obj &&
    'content' in obj
  );
}

2. Generic Response Types

// src/common/types/api-response.type.ts

export interface ApiResponse<T> {
  data: T;
  meta?: {
    count?: number;
    page?: number;
    totalPages?: number;
  };
}

Testing Our Type-Safe API

Here's an example of how to write tests that leverage our type system:

// src/posts/posts.service.spec.ts

import { Test } from '@nestjs/testing';
import { PostsService } from './posts.service';
import { PrismaService } from '../prisma/prisma.service';
import { CreatePostDto } from './dto/create-post.dto';

describe('PostsService', () => {
  let service: PostsService;
  let prisma: PrismaService;

  beforeEach(async () => {
    const module = await Test.createTestingModule({
      providers: [PostsService, PrismaService],
    }).compile();

    service = module.get<PostsService>(PostsService);
    prisma = module.get<PrismaService>(PrismaService);
  });

  it('should create a post', async () => {
    const dto: CreatePostDto = {
      title: 'Test Post',
      content: 'Test Content',
      categoryId: 1,
    };

    const created = await service.create(dto);
    expect(created.title).toBe(dto.title);
  });
});

Best Practices and Tips

Always Use Strict TypeScript Configuration

   {
     "compilerOptions": {
       "strict": true,
       "strictNullChecks": true,
       "strictPropertyInitialization": true
     }
   }

Leverage Prisma's Generated Types
- Use Prisma's generated types instead of creating your own interface definitions
- Take advantage of Prisma's type-safe query builders
Implement Custom Decorators for Common Validations

   export function IsNonEmptyString() {
     return applyDecorators(
       IsString(),
       IsNotEmpty(),
       Transform(({ value }) => value?.trim())
     );
   }

Use Enums for Type-Safe Constants

   export enum PostStatus {
     DRAFT = 'DRAFT',
     PUBLISHED = 'PUBLISHED',
     ARCHIVED = 'ARCHIVED'
   }

Conclusion

Building type-safe APIs with NestJS, Prisma, and TypeScript provides several benefits:

Catch errors at compile-time rather than runtime
Improved developer experience with better IDE support
Self-documenting code through type definitions
Reduced need for runtime validation
Better maintainability and refactoring capabilities

The combination of these tools creates a robust development environment where you can build APIs with confidence, knowing that many potential issues will be caught before they reach production.

Additional Resources

How are you using type safety in your NestJS applications? Share your experiences and best practices in the comments below!

Follow me for more articles on full-stack development, TypeScript, and software architecture.

🚀 Happy coding! 🚀

Web Performance Optimization Tips from My Latest Project

jordan wilfry — Tue, 31 Dec 2024 00:13:05 +0000

After spending months optimizing a large-scale e-commerce platform built with Next.js, Prisma, and NestJS, I've compiled the most impactful performance improvements that helped us achieve a 90+ Performance Score in Lighthouse. Let me share the exact implementations that made the difference.

1. Client-Side Optimizations That Actually Worked

Image Optimization: Beyond Basic Next/Image

Here's the evolution of our image handling strategy:

// Before: Basic Next/Image implementation
<Image
  src={product.imageUrl}
  width={300}
  height={200}
  alt={product.name}
/>

// After: Optimized implementation with art direction
function ProductImage({ product, sizes }) {
  const imageSizes = {
    mobile: { width: 300, height: 200 },
    tablet: { width: 600, height: 400 },
    desktop: { width: 900, height: 600 },
  }

  return (
    <picture>
      <source
        media="(min-width: 1024px)"
        srcSet={`${product.imageUrl}?w=900&q=75 1x, ${product.imageUrl}?w=1800&q=75 2x`}
      />
      <source
        media="(min-width: 768px)"
        srcSet={`${product.imageUrl}?w=600&q=75 1x, ${product.imageUrl}?w=1200&q=75 2x`}
      />
      <Image
        src={product.imageUrl}
        {...imageSizes.mobile}
        placeholder="blur"
        blurDataURL={product.thumbnailUrl}
        priority={product.isHero}
        alt={product.name}
        sizes={sizes || '(max-width: 768px) 100vw, 50vw'}
        className="object-cover rounded-lg"
      />
    </picture>
  )
}

This implementation resulted in:

40% faster Largest Contentful Paint (LCP)
Proper image sizing across devices
Optimized network requests with responsive images
Improved Core Web Vitals scores

React Component Performance Optimization

Here's a real-world example of how we optimized our product listing component:

import { memo, useMemo, useCallback, useState } from 'react'
import { useQuery } from '@tanstack/react-query'

// Before: Unoptimized component
function ProductList({ category }) {
  const [filters, setFilters] = useState({})
  const { data: products } = useQuery(['products', category, filters])

  return products?.map(product => (
    <ProductCard key={product.id} product={product} />
  ))
}

// After: Optimized implementation
const ProductCard = memo(({ product, onAddToCart }) => {
  const formattedPrice = useMemo(() => {
    return new Intl.NumberFormat('en-US', {
      style: 'currency',
      currency: 'USD'
    }).format(product.price)
  }, [product.price])

  return (
    <div className="product-card">
      <ProductImage product={product} sizes="(max-width: 768px) 100vw, 33vw" />
      <h2>{product.name}</h2>
      <p>{formattedPrice}</p>
    </div>
  )
}, (prevProps, nextProps) => {
  return prevProps.product.id === nextProps.product.id &&
         prevProps.product.price === nextProps.product.price
})

const ProductList = memo(({ category }) => {
  const [filters, setFilters] = useState({})
  const { data: products, isLoading } = useQuery({
    queryKey: ['products', category, filters],
    queryFn: () => fetchProducts({ category, ...filters }),
    staleTime: 1000 * 60 * 5, // 5 minutes
    placeholderData: keepPreviousData
  })

  const handleFilterChange = useCallback((newFilters) => {
    setFilters(prev => ({ ...prev, ...newFilters }))
  }, [])

  if (isLoading) return <ProductListSkeleton />

  return (
    <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
      {products?.map(product => (
        <ProductCard 
          key={product.id} 
          product={product}
        />
      ))}
    </div>
  )
})

Key optimizations:

Implemented proper memoization with specific comparison functions
Used React Query for automatic caching and request deduplication
Added loading skeletons for better perceived performance
Implemented virtualization for long lists

2. Server-Side Optimizations with NestJS and Prisma

API Route Optimization

Here's how we optimized our API routes:

// nestjs/products/products.service.ts
import { Injectable, CacheInterceptor, UseInterceptors } from '@nestjs/common'
import { PrismaService } from '../prisma/prisma.service'

@Injectable()
export class ProductsService {
  constructor(private prisma: PrismaService) {}

  @UseInterceptors(CacheInterceptor)
  async getProducts(params: {
    skip?: number
    take?: number
    category?: string
    search?: string
  }) {
    const { skip = 0, take = 10, category, search } = params

    // Optimize Prisma query
    const products = await this.prisma.product.findMany({
      where: {
        AND: [
          category ? { categoryId: category } : {},
          search ? {
            OR: [
              { name: { contains: search, mode: 'insensitive' } },
              { description: { contains: search, mode: 'insensitive' } }
            ]
          } : {}
        ]
      },
      include: {
        category: {
          select: {
            name: true
          }
        },
        images: {
          take: 1,
          select: {
            url: true
          }
        }
      },
      skip,
      take,
      orderBy: {
        createdAt: 'desc'
      }
    })

    const total = await this.prisma.product.count({
      where: {
        categoryId: category
      }
    })

    return {
      products,
      total,
      hasMore: skip + take < total
    }
  }
}

Prisma Query Optimization

Here's how we optimized our Prisma queries:

// prisma/schema.prisma
model Product {
  id          String   @id @default(cuid())
  name        String
  description String?
  price       Decimal
  categoryId  String
  category    Category @relation(fields: [categoryId], references: [id])
  images      Image[]
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt

  @@index([categoryId])
  @@index([name])
  @@index([createdAt])
}

// services/product.service.ts
async function getProductsWithRelations(filters: ProductFilters) {
  // Use transaction for multiple queries
  const [products, total] = await prisma.$transaction([
    prisma.product.findMany({
      where: buildWhereClause(filters),
      select: {
        id: true,
        name: true,
        price: true,
        category: {
          select: {
            name: true
          }
        },
        images: {
          take: 1,
          select: {
            url: true
          }
        }
      },
      skip: filters.skip,
      take: filters.take,
      orderBy: {
        createdAt: 'desc'
      }
    }),
    prisma.product.count({
      where: buildWhereClause(filters)
    })
  ])

  return { products, total }
}

// Middleware for query logging
prisma.$use(async (params, next) => {
  const before = Date.now()
  const result = await next(params)
  const after = Date.now()
  console.log(`Query ${params.model}.${params.action} took ${after - before}ms`)
  return result
})

Key Prisma optimizations:

Used proper indexes based on query patterns
Implemented selective field selection
Used transactions for multiple queries
Added query logging middleware for monitoring
Implemented connection pooling

3. Next.js Bundle Optimization

Implementing Module Optimization

// next.config.js
module.exports = {
  experimental: {
    optimizeCss: true,
    modern: true,
  },
  webpack: (config, { dev, isServer }) => {
    // Enable tree shaking
    if (!dev && !isServer) {
      config.optimization.splitChunks = {
        chunks: 'all',
        minSize: 20000,
        maxSize: 244000,
        minChunks: 1,
        maxAsyncRequests: 30,
        maxInitialRequests: 30,
        cacheGroups: {
          defaultVendors: {
            test: /[\\/]node_modules[\\/]/,
            priority: -10,
            reuseExistingChunk: true,
          },
          default: {
            minChunks: 2,
            priority: -20,
            reuseExistingChunk: true,
          },
        },
      }
    }
    return config
  },
}

Implementing Dynamic Imports

// pages/products/[id].tsx
import dynamic from 'next/dynamic'

const DynamicProductReviews = dynamic(
  () => import('../../components/ProductReviews'),
  {
    loading: () => <ReviewsSkeleton />,
    ssr: false
  }
)

const DynamicProductRecommendations = dynamic(
  () => import('../../components/ProductRecommendations'),
  {
    loading: () => <RecommendationsSkeleton />,
    ssr: false
  }
)

export default function ProductPage({ product }) {
  return (
    <div>
      <ProductHeader product={product} />
      <Suspense fallback={<ReviewsSkeleton />}>
        <DynamicProductReviews productId={product.id} />
      </Suspense>
      <Suspense fallback={<RecommendationsSkeleton />}>
        <DynamicProductRecommendations 
          categoryId={product.categoryId} 
        />
      </Suspense>
    </div>
  )
}

4. Performance Monitoring Setup

Here's our monitoring implementation:

// lib/analytics.ts
export function reportWebVitals(metric: any) {
  const body = {
    name: metric.name,
    value: metric.value,
    rating: metric.rating,
    delta: metric.delta,
    id: metric.id,
  }

  // Send to your analytics service
  fetch('/api/analytics', {
    method: 'POST',
    body: JSON.stringify(body),
    headers: {
      'Content-Type': 'application/json'
    }
  })
}

// pages/_app.tsx
export function reportWebVitals(metric: NextWebVitalsMetric) {
  switch (metric.name) {
    case 'FCP':
      console.log('FCP: ', metric.value)
      break
    case 'LCP':
      console.log('LCP: ', metric.value)
      break
    case 'CLS':
      console.log('CLS: ', metric.value)
      break
    case 'FID':
      console.log('FID: ', metric.value)
      break
    case 'TTFB':
      console.log('TTFB: ', metric.value)
      break
    default:
      break
  }

  // Report to analytics
  reportWebVitals(metric)
}

Results and Metrics

After implementing these optimizations, we achieved:

LCP reduced from 3.2s to 1.8s
FID improved from 180ms to 45ms
CLS score of 0.05 (from 0.25)
API response times reduced by 65%
Bundle size reduced by 45%
Database query times reduced by 70%

Conclusion

Performance optimization is an iterative process that requires continuous monitoring and adjustment. The techniques shared here transformed our application from having mediocre performance to consistently achieving 90+ Lighthouse scores.

The key takeaways are:

Always measure before optimizing
Focus on Core Web Vitals
Optimize images aggressively
Use proper database indexing
Implement effective caching strategies

What performance challenges have you faced in your projects? Share your experiences in the comments below!

Follow me for more web development tips and tricks!

Why Choose React Native for Cross-Platform Development in 2025

jordan wilfry — Fri, 20 Dec 2024 23:24:01 +0000

Introduction

Cross-platform development continues to be a crucial consideration for businesses and development teams. React Native has emerged as a leading solution, powering applications from startups to major platforms like Instagram, Walmart, and Discord. Through data-driven insights and technical evaluation, let's analyze why companies choose React Native.

Business Benefits

Cost-Efficiency

Statistical data from multiple case studies shows:

30-45% average reduction in development costs
40-60% faster time-to-market
Single team management instead of separate iOS/Android teams
Reduced maintenance costs through shared codebase

Market Reach

React Native enables simultaneous deployment to both platforms:

Access to both iOS and Android markets with one codebase
Faster feature parity across platforms
Consistent user experience

Technical Advantages

1. Code Sharing Efficiency

React Native enables significant code reuse:

// One component, multiple platforms
const PaymentCard = ({ payment }) => {
  return (
    <View style={styles.container}>
      <Text style={styles.amount}>
        ${payment.amount.toFixed(2)}
      </Text>
      {Platform.select({
        ios: <ApplePayButton />,
        android: <GooglePayButton />,
        default: <StandardPayButton />
      })}
    </View>
  );
};

2. Performance Capabilities

Modern React Native applications achieve near-native performance:

JavaScript Core Engine optimizations
Native modules for intensive tasks
Efficient bridge communication
Hardware acceleration support

// Example of performance optimization
import { useMemo } from 'react';
import { createNativeWrapper } from 'react-native-reanimated';

const OptimizedList = createNativeWrapper(({ data }) => {
  const memoizedData = useMemo(() => processData(data), [data]);

  return (
    <FlatList
      data={memoizedData}
      renderItem={({ item }) => <ListItem item={item} />}
      getItemLayout={(data, index) => ({
        length: ITEM_HEIGHT,
        offset: ITEM_HEIGHT * index,
        index,
      })}
    />
  );
});

3. Development Ecosystem

React Native provides a mature development environment:

Extensive third-party library support
Strong typing with TypeScript
Modern development tools
Active community support

4. Integration Capabilities

// Native module integration example
import { NativeModules } from 'react-native';

const BiometricAuth = NativeModules.BiometricAuth;

const authenticate = async () => {
  try {
    const result = await BiometricAuth.authenticate({
      reason: 'Verify your identity',
      fallbackLabel: 'Use passcode'
    });
    return result;
  } catch (error) {
    console.error('Biometric auth failed:', error);
  }
};

Common Use Cases

1. MVP Development

Rapid prototyping
Quick market validation
Easy iteration based on feedback

2. Enterprise Applications

Complex business logic implementation
Secure data handling
Integration with existing systems

3. E-commerce Solutions

Payment gateway integration
Real-time inventory management
Cross-platform shopping experience

Technical Considerations

When to Choose React Native

Medium to large applications requiring cross-platform presence
Projects with tight time-to-market requirements
Applications needing frequent updates
Teams with JavaScript/React expertise

When to Consider Alternatives

Highly specialized platform-specific features
Graphics-intensive applications
Low-level hardware integration requirements

Performance Metrics

Industry benchmarks show:

Initial load times within 1.5-2.5 seconds
Memory usage comparable to native apps
60fps animation capability
Bundle sizes optimized for both platforms

Implementation Strategy

// Modern architecture example
import { createNativeStackNavigator } from '@react-navigation/native-stack';
import { QueryClient, QueryClientProvider } from 'react-query';

const Stack = createNativeStackNavigator();
const queryClient = new QueryClient();

export default function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <NavigationContainer>
        <Stack.Navigator>
          <Stack.Screen 
            name="Home" 
            component={HomeScreen}
            options={{ animation: 'slide_from_right' }}
          />
        </Stack.Navigator>
      </NavigationContainer>
    </QueryClientProvider>
  );
}

Future Considerations

New architecture adoption
Improved performance with Fabric renderer
Enhanced type safety with TypeScript
Growing enterprise adoption

Conclusion

React Native presents a compelling solution for cross-platform development, particularly for businesses prioritizing time-to-market and resource efficiency. While not suitable for every use case, its maturity and ecosystem make it a strong contender for many mobile development projects.

#reactnative #javascript #mobile #webdev #programming

🚀 5 JavaScript Best Practices That Transformed My Code Quality

jordan wilfry — Fri, 20 Dec 2024 01:31:16 +0000

After years of web development, these practices have become non-negotiable in my workflow. Here's why:

1️⃣ Replace nested callbacks with async/await:

Before:

getData((result) => {
  processData(result, (processed) => {
    saveData(processed, (saved) => {
      console.log('Done!');
    });
  });
});

After:

async function handleData() {
  const result = await getData();
  const processed = await processData(result);
  await saveData(processed);
  console.log('Done!');
}

2️⃣ Use destructuring for cleaner code:

Before:

const user = getUser();
const name = user.name;
const email = user.email;

After:

const { name, email } = getUser();

3️⃣ Early returns to avoid nested conditions:

Before:

function processUser(user) {
  if (user) {
    if (user.isActive) {
      if (user.hasPermission) {
        // Do something
        return true;
      }
    }
  }
  return false;
}

After:

function processUser(user) {
  if (!user) return false;
  if (!user.isActive) return false;
  if (!user.hasPermission) return false;

  // Do something
  return true;
}

4️⃣ Use meaningful variable names:

Before:

const x = users.filter(u => u.a > 18);

After:

const activeUsers = users.filter(user => user.age > 18);

5️⃣ Implement proper error handling:

Before:

try {
  doSomething();
} catch (e) {
  console.log(e);
}

After:

try {
  await doSomething();
} catch (error) {
  logger.error('Operation failed:', {
    error: error.message,
    stack: error.stack,
    context: 'doSomething operation'
  });
  throw new CustomError('Operation failed', error);
}

💡 These practices have helped me:

Reduce bugs by 40%
Make code reviews faster
Make maintenance easier
Improve team collaboration

What's your favourite JavaScript best practice? Share in the comments! 👇

#webdevelopment #javascript #coding #programming #techinnovation #softwareengineering #developertips

Follow me for more web development tips and best practices! 🚀