nextjs-server-components

name	nextjs-server-components
user-invocable	false
description	Use when next.js Server Components for optimal performance. Use when building data-intensive Next.js applications.
allowed-tools	["Bash","Read"]

Next.js Server Components

Master Server Components in Next.js to build high-performance applications with server-side rendering and data fetching.

Server Components Basics

In Next.js App Router, all components are Server Components by default:

// app/posts/page.tsx (Server Component by default)
async function getPosts() {
  const res = await fetch('https://api.example.com/posts', {
    next: { revalidate: 3600 } // Cache for 1 hour
  });
  if (!res.ok) throw new Error('Failed to fetch posts');
  return res.json();
}

export default async function Posts() {
  const posts = await getPosts();

  return (
    <div>
      <h1>Blog Posts</h1>
      {posts.map((post: Post) => (
        <article key={post.id}>
          <h2>{post.title}</h2>
          <p>{post.content}</p>
          <span>{new Date(post.date).toLocaleDateString()}</span>
        </article>
      ))}
    </div>
  );
}

// Direct database access (server-only)
import { db } from '@/lib/db';

export default async function Users() {
  const users = await db.user.findMany({
    select: {
      id: true,
      name: true,
      email: true
    }
  });

  return (
    <div>
      {users.map(user => (
        <div key={user.id}>
          {user.name} - {user.email}
        </div>
      ))}
    </div>
  );
}

Server vs Client Components Decision Tree

// Use Server Components when:
// - Fetching data
// - Accessing backend resources directly
// - Keeping sensitive information on server
// - Keeping large dependencies on server

// Server Component (default)
export default async function ServerComp() {
  const data = await fetchData();
  return <div>{data}</div>;
}

// Use Client Components when:
// - Using interactivity (onClick, onChange, etc.)
// - Using state or lifecycle hooks (useState, useEffect)
// - Using browser-only APIs (localStorage, window, etc.)
// - Using custom hooks that depend on state/effects
// - Using React Context

// Client Component
'use client';
import { useState } from 'react';

export default function ClientComp() {
  const [count, setCount] = useState(0);

  return (
    <button onClick={() => setCount(count + 1)}>
      Count: {count}
    </button>
  );
}

// Composition: Server Component with Client Component
    () {
   data =  (); 

   (
    
  );
}

Server Actions for Mutations

// app/actions.ts - Server Actions
'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;

  const post = await db.post.create({
    data: { title, content }
  });

  revalidatePath('/posts');
  redirect(`/posts/${post.id}`);
}

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

   db..({
    : { id },
    : { title, content }
  });

  ();
   { :  };
}

   () {
   db..({ : { id } });
  ();
}


   () {
   (
    
  );
}


;
 { useFormStatus, useFormState }  ;
 { createPost }  ;

 () {
   { pending } = ();

   (
    
  );
}

   () {
   [state, formAction] = (createPost, );

   (
    
  );
}

Data Fetching Patterns

// Parallel data fetching
async function getUser(id: string) {
  const res = await fetch(`/api/users/${id}`);
  return res.json();
}

async function getUserPosts(id: string) {
  const res = await fetch(`/api/users/${id}/posts`);
  return res.json();
}

export default async function UserProfile({ params }: {
  params: { id: string }
}) {
  // Fetch in parallel
  const [user, posts] = await Promise.all([
    getUser(params.id),
    getUserPosts(params.id)
  ]);

  return (
    <div>
      <UserInfo user={user} />
      <UserPosts posts={posts} />
    
  );
}


    () {
  
   user =  ();

  
   settings =  (user.);
   notifications =  (user.);

   (
    
  );
}


 {  }  ;

   () {
   (
    
  );
}

Streaming with Suspense

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

export default function Dashboard() {
  return (
    <div>
      <h1>Dashboard</h1>

      {/* Fast component renders immediately */}
      <QuickStats />

      {/* Slow components stream in */}
      <Suspense fallback={<ChartSkeleton />}>
        <RevenueChart />
      </Suspense>

      <Suspense fallback={<TableSkeleton />}>
        <RecentOrders />
      </Suspense>

      <Suspense fallback={<ActivitySkeleton />}>
        <ActivityFeed />
      </Suspense>
    </div>
  );
}

async function RevenueChart() {
  // Slow data fetch
  const data = await fetchRevenueData();

   ;
}

  () {
   orders =  ({ :  });

   (
    
  );
}


  () {
   (
    
  );
}

Server Component Patterns

// Pattern 1: Data fetching in Server Component
async function fetchProduct(id: string) {
  const product = await db.product.findUnique({ where: { id } });
  return product;
}

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

  return (
    <div>
      <ProductDetails product={product} />
      <AddToCartButton productId={product.id} /> {/* Client Component */}
    </div>
  );
}

// Pattern 2: Server Component as data provider
async function ProductWithReviews({ id }: { id: string }) {
  const [product, reviews] = await Promise.all([
    fetchProduct(id),
    fetchReviews(id)
  ]);

  return (
    
      
      
       {/* Client Component */}
    
  );
}


    () {
   data =  ();

   (
    
  );
}


    () {
   user =  ();

   (
    
  );
}

Client Component Patterns

// Pattern 1: Minimal Client Component
'use client';
import { useState } from 'react';

export function Counter({ initialCount = 0 }: { initialCount?: number }) {
  const [count, setCount] = useState(initialCount);

  return (
    <button onClick={() => setCount(count + 1)}>
      Count: {count}
    </button>
  );
}

// Pattern 2: Client Component with Server Component children
'use client';
import { useState } from 'react';

export function Tabs({ children }: { children: React.ReactNode }) {
  const [activeTab, setActiveTab] = useState(0);

  return (
    <div>
      <div className="tabs">
        <button onClick={() => setActiveTab(0)}>Tab 1</button>
        <button onClick={() => setActiveTab(1)}>Tab 2</button>
      </>
      {children}
    
  );
}


    () {
   data =  ();

   (
    
  );
}


;
 { createContext, useContext, useState }  ;

  = createContext<{
  : ;
  :  ;
} | >();

  () {
   [theme, setTheme] = ();

   (
    
  );
}


;
 { useOptimistic }  ;
 { addTodo }  ;

  () {
   [optimisticTodos, addOptimisticTodo] = (
    todos,
     [
      ...state,
      { : .(), : newTodo, :  }
    ]
  );

    () {
     text = formData.()  ;
    (text);
     (text);
  }

   (
    
  );
}

Composition Strategies

// Strategy 1: Server Component as layout
export default async function Layout({
  children
}: {
  children: React.ReactNode
}) {
  const user = await getUser();

  return (
    <div>
      <ServerNav user={user} />
      <Sidebar>
        <ClientSidebarContent /> {/* Interactive sidebar */}
      </Sidebar>
      <main>{children}</main>
    </div>
  );
}

// Strategy 2: Passing Server Components as props
export default async function Page() {
  const posts = await getPosts();

  return (
    <ClientLayout
      sidebar={<ServerSidebar posts={posts} />}
      main={<ServerContent posts={posts} />}
    />
  );
}

// Strategy 3: Server Component with multiple Client Components
export    () {
   data =  ();

   (
    
  );
}


    () {
   user =  ();

   (
    
  );
}

Server-Only Code

// lib/server-only-utils.ts
import 'server-only'; // Ensures this file is never bundled for client

export async function getSecretData() {
  const apiKey = process.env.SECRET_API_KEY;
  // This code only runs on server
  const res = await fetch('https://api.example.com/secret', {
    headers: {
      Authorization: `Bearer ${apiKey}`
    }
  });
  return res.json();
}

export function decryptData(encrypted: string) {
  // Encryption logic that should never reach client
  return decrypt(encrypted, process.env.ENCRYPTION_KEY);
}

// app/dashboard/page.tsx
import { getSecretData } from '@/lib/server-only-utils';

export default async function Dashboard() {
  const data = await getSecretData();

  return <div>{data.publicInfo};
}



 ;

  env = {
  : process..!,
  : process..!,
  : process..!
}  ;


 { env }  ;

    () {
   data =  (, {
    : { : env. }
  });

   ;
}

Performance Implications

// Heavy dependency only loaded on server
import { marked } from 'marked'; // Markdown parser (large library)

export default async function MarkdownPage({ content }: {
  content: string
}) {
  // This runs only on server, keeping bundle small
  const html = marked(content);

  return <div dangerouslySetInnerHTML={{ __html: html }} />;
}

// Image optimization on server
import sharp from 'sharp'; // Image processing library

export default async function OptimizedImage({ src }: { src: string }) {
  // Process on server
  const buffer = await fetch(src).then(r => r.arrayBuffer());
  const optimized = await sharp(buffer)
    .resize(800, 600)
    .webp()
    .toBuffer();

   base64 = optimized.();

   ;
}


    () {
  
   rawData =  ();
   processed = (rawData); 
   stats = (processed); 

   ;
}


    () {
   [analytics, sales, inventory] =  .([
    (),
    (),
    ()
  ]);

   report = (analytics, sales, inventory);

   ;
}

Error Handling in Server Components

// Throwing errors in Server Components
export default async function PostPage({ params }: {
  params: { id: string }
}) {
  const post = await db.post.findUnique({
    where: { id: params.id }
  });

  if (!post) {
    throw new Error('Post not found');
  }

  return <Article post={post} />;
}

// Using notFound() for 404s
import { notFound } from 'next/navigation';

export default async function UserPage({ params }: {
  params: { id: string }
}) {
  const user = await db.user.findUnique({
    where: { id: params.id }
  });

  if (!user) {
    notFound(); // Renders not-found.tsx
  }

  return <UserProfile user={user} />;
}


    () {
   {
     data =  ();
     ;
  }  (error) {
    .(, error);
     ;
  }
}



    () {
   data =  (); 

   ;
}

When to Use This Skill

Use nextjs-server-components when you need to:

• Fetch data on the server
• Access backend resources directly
• Keep sensitive data server-side
• Reduce client bundle size
• Improve initial page load
• Build SEO-optimized pages
• Stream content to the client
• Implement zero-JS pages
• Optimize for performance
• Access databases directly
• Use server-only libraries
• Perform heavy computations

Best Practices

1. Use server components by default - Only add 'use client' when you need interactivity, state, or browser APIs.

2. Fetch data close to where it's used - Colocate data fetching with the components that use the data.

3. Leverage parallel data fetching - Use Promise.all to fetch independent data sources simultaneously.

4. Use streaming for better UX - Wrap slow components in Suspense to show content as it loads.

5. Keep sensitive logic server-side - Database queries, API keys, and business logic should stay on server.

6. Minimize client components - Each 'use client' boundary increases JavaScript bundle size.

7. Cache data appropriately - Use Next.js caching strategies (revalidate, no-store) based on data freshness needs.

8. Handle errors gracefully - Use error boundaries and not-found pages for better error handling.

9. Use TypeScript for type safety - Define proper types for props and data to catch errors early.

10. Test server component behavior - Verify data fetching, error handling, and rendering in tests.

Common Pitfalls

1. Using client-only APIs in server components - window, localStorage, document are not available on server.

2. Not handling async errors properly - Unhandled promise rejections crash the entire page.

3. Mixing server and client state - State management libraries don't work in server components.

4. Overusing client components - Adding 'use client' unnecessarily increases bundle size and reduces performance.

5. Not leveraging data streaming - Missing Suspense boundaries cause slow page loads instead of progressive rendering.

6. Ignoring caching strategies - Not setting revalidate times leads to stale data or unnecessary requests.

7. Not optimizing data fetching - Sequential fetches cause waterfalls; use parallel fetching when possible.

8. Exposing sensitive data - Accidentally passing secrets or API keys to client components.

9. Not handling loading states - Missing loading UI during data fetching creates poor user experience.

10. Misunderstanding component boundaries - Server components can't be imported into client components directly.

Resources

• Next.js Server Components
• Client Components
• Composition Patterns
• Server Actions
• Data Fetching
• React Server Components