---

name: bellog-rsc description: Provides guidance on React Server Components vs Client Components decision-making in Bellog. Triggers when creating new components.

Bellog Server/Client Components

This skill defines when to use Server Components vs Client Components in the Bellog blog project.

Core Principle

Default to Server Components. Only use Client Components when necessary.

Decision Tree

Does the component need interactivity or browser APIs?
│
├─ NO (static rendering)
│  └─ ✅ Server Component
│     - Fast initial load
│     - Zero client JavaScript
│     - Can use async/await directly
│     - Can access server-only APIs
│     - Better SEO
│
└─ YES (hooks, events, browser APIs)
   └─ 🔴 Client Component ("use client")
      - Can use hooks (useState, useEffect, etc.)
      - Can attach event handlers
      - Can access browser APIs
      - Can use framer-motion
      - Can use next-themes

Server Components (Default)

When to Use

✅ Use Server Components when:

• Rendering static content
• Fetching data from APIs or databases
• Reading from the filesystem
• No interactivity needed
• Pure presentation components
• SEO is critical

Characteristics

// ✅ Server Component (no "use client")

import { getAllPosts } from '@/lib/posts';

export default async function PostList() {
  // Can use async/await directly
  const posts = await getAllPosts();

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

Benefits

• Performance: No JavaScript sent to client
• SEO: Fully rendered HTML
• Data fetching: Direct database/API access
• Security: Can use secrets safely
• Caching: Automatic request memoization

Examples in Bellog

Server Components:

• app/page.tsx - Home page (fetches recent posts)
• app/posts/page.tsx - Posts list (fetches all posts)
• app/posts/[slug]/page.tsx - Post detail (fetches single post)
• PostList component - Renders static post grid
• PostCard component - Static card rendering

Client Components

When to Use

🔴 Use Client Components when you need:

1. React Hooks:

• useState, useEffect, useContext
• useRef, useCallback, useMemo
• Custom hooks (useScrollSpy, etc.)

2. Event Handlers:

• onClick, onChange, onSubmit
• onScroll, onMouseEnter, onMouseLeave
• Form interactions

3. Browser APIs:

• window, document, localStorage
• IntersectionObserver, ResizeObserver
• navigator, location

4. Third-Party Libraries:

• framer-motion - Requires client
• next-themes - Theme toggle requires client
• Any library that uses browser APIs

Characteristics

"use client"; // Required at top of file

import { useState } from 'react';
import { motion } from 'framer-motion';

export function InteractiveCard() {
  const [isHovered, setIsHovered] = useState(false);

  return (
    <motion.div
      onMouseEnter={() => setIsHovered(true)}
      onMouseLeave={() => setIsHovered(false)}
      whileHover={{ scale: 1.02 }}
    >
      {/* Interactive content */}
    </motion.div>
  );
}

Examples in Bellog

Client Components:

• Navbar.tsx - Scroll detection, theme toggle
• Intro.tsx - TypeAnimation, framer-motion
• NotionToc.tsx - Scroll spy, active section tracking
• template.tsx - Page transition animations
• ThemeToggle.tsx - next-themes integration
• ProgressBar.tsx - Scroll progress tracking
• GiscusComments.tsx - Comment system (requires client JS)

Common Patterns

Pattern 1: Server Component with Client Island

Best Practice: Keep most as Server, wrap interactive parts as Client.

// app/posts/[slug]/page.tsx (Server Component)
import { getPostBySlug } from '@/lib/posts';
import { NotionToc } from '@/components/posts/NotionToc'; // Client
import { PostNavigation } from '@/components/posts/PostNavigation'; // Client
import { PostRenderer } from '@/components/posts/PostRenderer'; // Server

export default async function PostPage({ params }) {
  const post = await getPostBySlug(params.slug);

  return (
    <div>
      <NotionToc headings={post.headings} /> {/* Client island */}
      <PostRenderer content={post.content} /> {/* Server */}
      <PostNavigation prev={post.prev} next={post.next} /> {/* Client */}
    </div>
  );
}

Pattern 2: Passing Data from Server to Client

// Server Component
async function ParentServer() {
  const data = await fetchData(); // Server-side fetch

  return <ChildClient data={data} />; // Pass as props
}

// Client Component
"use client";

function ChildClient({ data }) {
  const [selected, setSelected] = useState(data[0]);
  // Use data in client component
}

Important: Don't pass functions or Date objects - serialize data!

// ❌ Wrong
<ClientComponent date={new Date()} />

// ✅ Correct
<ClientComponent date={new Date().toISOString()} />

Pattern 3: Composition Pattern

Wrap Client Component to Reduce Bundle:

// Layout (Server Component)
import { ClientHeader } from './ClientHeader';

export function Layout({ children }) {
  return (
    <>
      <ClientHeader /> {/* Only this is client */}
      <main>{children}</main> {/* Can be server */}
    </>
  );
}

Caching Patterns (Server Components)

React cache()

import { cache } from 'react';

// Deduplicates requests within a single render
export const getPost = cache(async (id: string) => {
  return await fetchPost(id);
});

Next.js unstable_cache()

import { cache } from 'react';
import { unstable_cache } from 'next/cache';

export const getAllPosts = cache(
  unstable_cache(
    async () => {
      return await getAllPostsFromNotion();
    },
    ['all-posts'], // Cache key
    {
      revalidate: 3600, // 1 hour
      tags: ['posts', 'notion']
    }
  )
);

Example from /src/lib/posts.ts:

export const getAllPosts = cache(
  unstable_cache(
    async () => {
      const posts = await getAllPostsFromNotion();
      return posts.sort((a, b) =>
        new Date(b.date).getTime() - new Date(a.date).getTime()
      );
    },
    ["all-posts"],
    {
      revalidate: 3600, // Revalidate every hour
      tags: ["posts", "notion"]
    }
  )
);

On-Demand Revalidation

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

export async function POST(request: Request) {
  const secret = request.nextUrl.searchParams.get('secret');

  if (secret !== process.env.REVALIDATION_SECRET) {
    return Response.json({ message: 'Invalid' }, { status: 401 });
  }

  revalidateTag('notion'); // Invalidate all Notion caches

  return Response.json({ revalidated: true });
}

Common Mistakes

Mistake 1: Unnecessary "use client"

// ❌ Wrong (doesn't need "use client")
"use client";

export function StaticCard({ title, description }) {
  return (
    <div>
      <h3>{title}</h3>
      <p>{description}</p>
    </div>
  );
}

// ✅ Correct (Server Component)
export function StaticCard({ title, description }) {
  return (
    <div>
      <h3>{title}</h3>
      <p>{description}</p>
    </div>
  );
}

Mistake 2: Missing "use client"

// ❌ Wrong (needs "use client" because of useState)
import { useState } from 'react';

export function Counter() {
  const [count, setCount] = useState(0); // Error!
  return <button onClick={() => setCount(count + 1)}>{count}</button>;
}

// ✅ Correct
"use client";

import { useState } from 'react';

export function Counter() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(count + 1)}>{count}</button>;
}

Mistake 3: Async Client Component

// ❌ Wrong (Client Components can't be async)
"use client";

export default async function Page() {
  const data = await fetchData(); // Error!
  return <div>{data}</div>;
}

// ✅ Correct (Server Component)
export default async function Page() {
  const data = await fetchData();
  return <ClientChild data={data} />;
}

Mistake 4: Passing Functions as Props

// ❌ Wrong (functions can't be serialized)
async function ServerComponent() {
  const handler = () => console.log('click');
  return <ClientComponent onClick={handler} />; // Error!
}

// ✅ Correct (define handler in client component)
"use client";

function ClientComponent() {
  const handler = () => console.log('click');
  return <button onClick={handler}>Click</button>;
}

Component Type Checklist

When creating a component, ask:

• Does it use hooks? → Client
• Does it have event handlers? → Client
• Does it use framer-motion? → Client
• Does it use next-themes? → Client
• Does it access window/document? → Client
• Does it need browser APIs? → Client
• Otherwise → Server

If any checkbox is true, use "use client". Otherwise, keep as Server Component.

Performance Impact

Server Components

Bundle Size: 0 KB (no client JavaScript) Initial Load: Fast (pre-rendered HTML) Hydration: None needed SEO: Excellent (fully rendered)

Client Components

Bundle Size: Adds JavaScript to bundle Initial Load: Slower (needs hydration) Hydration: Required SEO: Good (but requires hydration)

Example:

• Navbar.tsx (Client): ~5 KB
• Intro.tsx with framer-motion (Client): ~30 KB
• PostList (Server): 0 KB

Best Practices

1. Start with Server

// Always start here
export function Component() {
  // ...
}

// Only add "use client" when needed

2. Minimize Client Boundaries

// ✅ Good - Only button is client
function Page() {
  return (
    <div>
      <StaticContent /> {/* Server */}
      <InteractiveButton /> {/* Client */}
    </div>
  );
}

// ❌ Bad - Everything is client
"use client";

function Page() {
  return (
    <div>
      <StaticContent /> {/* Unnecessary client */}
      <InteractiveButton />
    </div>
  );
}

3. Extract Client Logic

// ✅ Extract interactive part
function ServerCard({ data }) {
  return (
    <div>
      <StaticHeader data={data} /> {/* Server */}
      <InteractiveActions id={data.id} /> {/* Client */}
    </div>
  );
}

"use client";

function InteractiveActions({ id }) {
  const [liked, setLiked] = useState(false);
  return <button onClick={() => setLiked(!liked)}>Like</button>;
}

4. Use Composition

// Layout stays Server
function Layout({ children }) {
  return (
    <>
      <Header /> {/* Client component */}
      <main>{children}</main> {/* Can be Server */}
      <Footer /> {/* Server component */}
    </>
  );
}

Quick Reference

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

// Client Component (when needed)
"use client";

import { useState } from 'react';

export function Component() {
  const [state, setState] = useState();
  return <button onClick={() => setState(...)}>Click</button>;
}

// Client with framer-motion
"use client";

import { motion } from 'framer-motion';

export function Component() {
  return <motion.div animate={{ opacity: 1 }}>...</motion.div>;
}

// Pass data Server → Client
function Server() {
  const data = await fetch();
  return <Client data={data} />; // Serialize data
}

Remember: Every "use client" adds to bundle size. Be intentional about where you place client boundaries.