React Server Components

Build performant applications with React Server Components and Next.js App Router.

Core Workflow Understand RSC model: Server vs client components Design component tree: Plan server/client boundaries Implement data fetching: Fetch in server components Add interactivity: Client components where needed Enable streaming: Suspense for progressive loading Optimize: Minimize client bundle size Server vs Client Components Key Differences Feature Server Components Client Components Rendering Server only Server + Client Bundle size Zero JS sent Adds to bundle Data fetching Direct DB/API access useEffect/TanStack Query State/Effects No hooks Full React hooks Event handlers No Yes Browser APIs No Yes File directive Default (none) 'use client' When to Use Each

Server Components (Default)

Static content Data fetching Backend resource access Large dependencies (markdown, syntax highlighting) Sensitive logic/tokens

Client Components

Interactive UI (onClick, onChange) useState, useEffect, useReducer Browser APIs (localStorage, geolocation) Custom hooks with state Third-party client libraries Basic Patterns Server Component (Default) // app/users/page.tsx (Server Component - no directive needed) import { db } from '@/lib/db';

async function getUsers() { return db.user.findMany({ orderBy: { createdAt: 'desc' }, }); }

export default async function UsersPage() { const users = await getUsers();

return (

Users

{user.name}

); }

Client Component // components/Counter.tsx 'use client';

import { useState } from 'react';

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

return ( ); }

Composition Pattern // app/dashboard/page.tsx (Server Component) import { db } from '@/lib/db'; import { DashboardClient } from './DashboardClient'; import { StatsCard } from '@/components/StatsCard';

async function getStats() { const [users, orders, revenue] = await Promise.all([ db.user.count(), db.order.count(), db.order.aggregate({ _sum: { total: true } }), ]); return { users, orders, revenue: revenue._sum.total }; }

export default async function DashboardPage() { const stats = await getStats();

return (

{/ Server-rendered static content /}

Dashboard

  {/* Server components with data */}
  <div className="grid grid-cols-3 gap-4">
    <StatsCard title="Users" value={stats.users} />
    <StatsCard title="Orders" value={stats.orders} />
    <StatsCard title="Revenue" value={`$${stats.revenue}`} />
  </div>

  {/* Client component for interactivity */}
  <DashboardClient initialData={stats} />
</div>

); }

// app/dashboard/DashboardClient.tsx 'use client';

import { useState } from 'react'; import { DateRangePicker } from '@/components/DateRangePicker'; import { Chart } from '@/components/Chart';

interface DashboardClientProps { initialData: Stats; }

export function DashboardClient({ initialData }: DashboardClientProps) { const [dateRange, setDateRange] = useState({ from: null, to: null });

return (

); }

Data Fetching Patterns Parallel Data Fetching // app/page.tsx async function getUser(id: string) { const res = await fetch(/api/users/${id}); return res.json(); }

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

async function getComments(userId: string) { const res = await fetch(/api/users/${userId}/comments); return res.json(); }

export default async function ProfilePage({ params }: { params: { id: string } }) { // Parallel fetching - all requests start simultaneously const [user, posts, comments] = await Promise.all([ getUser(params.id), getPosts(params.id), getComments(params.id), ]);

return (

); }

Sequential Data Fetching (When Dependent) export default async function OrderPage({ params }: { params: { id: string } }) { // Sequential - second fetch depends on first const order = await getOrder(params.id); const customer = await getCustomer(order.customerId);

return (

); }

Caching and Revalidation // Static data (cached indefinitely) async function getStaticData() { const res = await fetch('https://api.example.com/static', { cache: 'force-cache', // Default }); return res.json(); }

// Dynamic data (no cache) async function getDynamicData() { const res = await fetch('https://api.example.com/dynamic', { cache: 'no-store', }); return res.json(); }

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

// Revalidate by tag async function getTaggedData() { const res = await fetch('https://api.example.com/products', { next: { tags: ['products'] }, }); return res.json(); }

// Trigger revalidation import { revalidateTag } from 'next/cache'; revalidateTag('products');

Streaming with Suspense Page-Level Streaming // app/dashboard/page.tsx import { Suspense } from 'react'; import { StatsCards, StatsCardsSkeleton } from './StatsCards'; import { RecentOrders, RecentOrdersSkeleton } from './RecentOrders'; import { TopProducts, TopProductsSkeleton } from './TopProducts';

export default function DashboardPage() { return (

Dashboard

  {/* Each section streams independently */}
  <Suspense fallback={<StatsCardsSkeleton />}>
    <StatsCards />
  </Suspense>

  <div className="grid grid-cols-2 gap-4 mt-8">
    <Suspense fallback={<RecentOrdersSkeleton />}>
      <RecentOrders />
    </Suspense>

    <Suspense fallback={<TopProductsSkeleton />}>
      <TopProducts />
    </Suspense>
  </div>
</div>

); }

Component with Data // app/dashboard/StatsCards.tsx import { db } from '@/lib/db';

async function getStats() { // Simulate slow query await new Promise((resolve) => setTimeout(resolve, 2000)); return db.stats.findFirst(); }

export async function StatsCards() { const stats = await getStats();

return (

); }

export function StatsCardsSkeleton() { return (

{[...Array(4)].map((_, i) => (

))}

); }

Loading States // app/products/loading.tsx export default function ProductsLoading() { return (

{[...Array(9)].map((_, i) => (

))}

); }

Server Actions Form Actions // app/contact/page.tsx import { submitContact } from './actions';

export default function ContactPage() { return (

<button type="submit">Send</button>
    </form>
  );
}</p>
<p>// app/contact/actions.ts
'use server';</p>
<p>import { z } from 'zod';
import { revalidatePath } from 'next/cache';</p>
<p>const schema = z.object({
  email: z.string().email(),
  message: z.string().min(10),
});</p>
<p>export async function submitContact(formData: FormData) {
  const validatedFields = schema.safeParse({
    email: formData.get('email'),
    message: formData.get('message'),
  });</p>
<p>if (!validatedFields.success) {
    return { error: validatedFields.error.flatten().fieldErrors };
  }</p>
<p>await db.contact.create({
    data: validatedFields.data,
  });</p>
<p>revalidatePath('/contacts');
  return { success: true };
}</p>
<p>With useActionState
// components/ContactForm.tsx
'use client';</p>
<p>import { useActionState } from 'react';
import { submitContact } from '@/app/contact/actions';</p>
<p>export function ContactForm() {
  const [state, formAction, isPending] = useActionState(submitContact, null);</p>
<p>return (
    <form action={formAction}>
      <input name="email" type="email" required />
      {state?.error?.email && <p className="text-red-500">{state.error.email}</p>}</p>
<pre class="codehilite"><code>  <textarea name="message" required />
  {state?.error?.message && <p className="text-red-500">{state.error.message}</p>}

<button type="submit" disabled={isPending}>
    {isPending ? 'Sending...' : 'Send'}
  </button>

{state?.success && <p className="text-green-500">Message sent!</p>}
</form>
</code></pre>

<p>);
}</p>
<p>Optimistic Updates
// components/LikeButton.tsx
'use client';</p>
<p>import { useOptimistic, useTransition } from 'react';
import { likePost } from '@/app/actions';</p>
<p>interface LikeButtonProps {
  postId: string;
  initialLikes: number;
  isLiked: boolean;
}</p>
<p>export function LikeButton({ postId, initialLikes, isLiked }: LikeButtonProps) {
  const [isPending, startTransition] = useTransition();
  const [optimisticState, addOptimistic] = useOptimistic(
    { likes: initialLikes, isLiked },
    (state, newIsLiked: boolean) => ({
      likes: newIsLiked ? state.likes + 1 : state.likes - 1,
      isLiked: newIsLiked,
    })
  );</p>
<p>const handleClick = () => {
    startTransition(async () => {
      addOptimistic(!optimisticState.isLiked);
      await likePost(postId);
    });
  };</p>
<p>return (
    <button onClick={handleClick} disabled={isPending}>
      {optimisticState.isLiked ? '❤️' : '🤍'} {optimisticState.likes}
    </button>
  );
}</p>
<p>Patterns for Common Use Cases
Authentication Check
// app/dashboard/layout.tsx
import { redirect } from 'next/navigation';
import { getSession } from '@/lib/auth';</p>
<p>export default async function DashboardLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  const session = await getSession();</p>
<p>if (!session) {
    redirect('/login');
  }</p>
<p>return (
    <div>
      <nav>Welcome, {session.user.name}</nav>
      {children}
    </div>
  );
}</p>
<p>Passing Server Data to Client
// app/products/[id]/page.tsx
import { getProduct } from '@/lib/products';
import { ProductGallery } from './ProductGallery';</p>
<p>export default async function ProductPage({ params }: { params: { id: string } }) {
  const product = await getProduct(params.id);</p>
<p>return (
    <div>
      <h1>{product.name}</h1>
      <p>{product.description}</p></p>
<pre class="codehilite"><code>  {/* Pass serializable data to client component */}
  <ProductGallery
    images={product.images}
    initialIndex={0}
  />
</div>
</code></pre>

<p>);
}</p>
<p>Nested Client Components
// components/Modal.tsx
'use client';</p>
<p>import { createContext, useContext, useState } from 'react';</p>
<p>const ModalContext = createContext<{
  open: boolean;
  setOpen: (open: boolean) => void;
} | null>(null);</p>
<p>export function ModalProvider({ children }: { children: React.ReactNode }) {
  const [open, setOpen] = useState(false);
  return (
    <ModalContext.Provider value={{ open, setOpen }}>
      {children}
    </ModalContext.Provider>
  );
}</p>
<p>export function useModal() {
  const context = useContext(ModalContext);
  if (!context) throw new Error('useModal must be used within ModalProvider');
  return context;
}</p>
<p>Best Practices
Start with Server Components: Default to server, add 'use client' only when needed
Push client boundaries down: Keep interactivity in leaf components
Parallel fetch data: Use Promise.all for independent data
Use Suspense for streaming: Progressive loading for better UX
Colocate data fetching: Fetch where data is used
Minimize client bundle: Heavy libraries stay on server
Cache appropriately: Use revalidation strategies
Handle errors: Use error.tsx boundaries
Output Checklist</p>
<p>Every RSC implementation should include:</p>
<p>Server components for data fetching
 'use client' only where needed
 Suspense boundaries for streaming
 Loading skeletons for each section
 Parallel data fetching with Promise.all
 Server actions for mutations
 Proper caching strategy
 Error boundaries (error.tsx)
 Authentication checks in layouts
 Minimal client JavaScript bundle</p>
                </article>

<a href="/" class="back-link">← <span data-i18n="detail.backToLeaderboard">返回排行榜</span></a>
            </div>

<aside class="sidebar">
                <section class="related-skills" id="relatedSkillsSection">
                    <h2 class="related-title" data-i18n="detail.relatedSkills">相关 Skills</h2>
                    <div class="related-list" id="relatedSkillsList">
                        
                        <div class="skeleton-card"></div>
                        <div class="skeleton-card"></div>
                        <div class="skeleton-card"></div>
                    </div>
                </section>
            </aside>
        </div>
    </div>

// Load language files (only current + fallback for performance)
        async function loadLanguageResources() {
            const savedLang = localStorage.getItem('i18nextLng') || 'en';
            const langsToLoad = new Set([savedLang, 'en']); // current + fallback
            await Promise.all([...langsToLoad].map(async (lang) => {
                try {
                    const response = await fetch(`/locales/${lang}.json`);
                    if (response.ok) {
                        resources[lang] = { translation: await response.json() };
                    }
                } catch (error) {
                    console.warn(`Failed to load ${lang} language file:`, error);
                }
            }));
        }

// Load a single language on demand (for language switching)
        async function loadLanguage(lang) {
            if (resources[lang]) return;
            try {
                const response = await fetch(`/locales/${lang}.json`);
                if (response.ok) {
                    resources[lang] = { translation: await response.json() };
                    i18next.addResourceBundle(lang, 'translation', resources[lang].translation);
                }
            } catch (error) {
                console.warn(`Failed to load ${lang} language file:`, error);
            }
        }

// Initialize i18next
        async function initI18n() {
            try {
                await loadLanguageResources();
                
                // Filter out null values from resources
                const validResources = {};
                for (const [lang, data] of Object.entries(resources)) {
                    if (data !== null) {
                        validResources[lang] = data;
                    }
                }
                
                console.log('Loaded languages:', Object.keys(validResources));
                console.log('zh-CN resource:', validResources['zh-CN']);
                console.log('detail.home in resource:', validResources['zh-CN']?.translation?.detail?.home);
                
                // 检查是否有保存的语言偏好
                const savedLang = localStorage.getItem('i18nextLng');
                // 如果没有保存的语言偏好，默认使用英文
                const defaultLang = savedLang && ['zh-CN', 'en', 'ja', 'ko', 'zh-TW', 'es', 'fr'].includes(savedLang) 
                    ? savedLang 
                    : 'en';
                
                await i18next
                    .use(i18nextBrowserLanguageDetector)
                    .init({
                        lng: defaultLang,  // 强制设置初始语言
                        fallbackLng: 'en',
                        supportedLngs: ['zh-CN', 'en', 'ja', 'ko', 'zh-TW', 'es', 'fr'],
                        resources: validResources,
                        detection: {
                            order: ['localStorage'],  // 只使用 localStorage，不检测浏览器语言
                            caches: ['localStorage'],
                            lookupLocalStorage: 'i18nextLng'
                        },
                        interpolation: {
                            escapeValue: false
                        }
                    });

console.log('i18next initialized, language:', i18next.language);
                console.log('Test translation:', i18next.t('detail.home'));

// Set initial language in selector
                const langSwitcher = document.getElementById('langSwitcher');
                langSwitcher.value = i18next.language;

// Update page language
                updatePageLanguage();

// Language switch event
                langSwitcher.addEventListener('change', async (e) => {
                    await loadLanguage(e.target.value); // load on demand
                    i18next.changeLanguage(e.target.value).then(() => {
                        updatePageLanguage();
                        localStorage.setItem('i18nextLng', e.target.value);
                    });
                });
            } catch (error) {
                console.error('i18next init failed:', error);
            }
        }

// Translation helper
        function t(key, options = {}) {
            return i18next.t(key, options);
        }

// Update all translatable elements
        function updatePageLanguage() {
            // Update HTML lang attribute
            document.documentElement.lang = i18next.language;

// Update elements with data-i18n attribute
            document.querySelectorAll('[data-i18n]').forEach(el => {
                const key = el.getAttribute('data-i18n');
                el.textContent = t(key);
            });
        }

// Copy command function
        function copyCommand() {
            const command = document.getElementById('installCommand').textContent;
            const btn = document.getElementById('copyBtn');
            
            navigator.clipboard.writeText(command).then(() => {
                btn.textContent = t('copied');
                btn.classList.add('copied');
                setTimeout(() => {
                    btn.textContent = t('copy');
                    btn.classList.remove('copied');
                }, 2000);
            }).catch(() => {
                // Fallback for non-HTTPS
                const textArea = document.createElement('textarea');
                textArea.value = command;
                textArea.style.position = 'fixed';
                textArea.style.left = '-9999px';
                document.body.appendChild(textArea);
                textArea.select();
                document.execCommand('copy');
                document.body.removeChild(textArea);
                
                btn.textContent = t('copied');
                btn.classList.add('copied');
                setTimeout(() => {
                    btn.textContent = t('copy');
                    btn.classList.remove('copied');
                }, 2000);
            });
        }

// Initialize
        document.getElementById('copyBtn').addEventListener('click', copyCommand);
        initI18n();

// 异步加载相关 Skills
        async function loadRelatedSkills() {
            const owner = 'patricio0312rev';
            const skillName = 'react-server-components';
            const currentLang = 'fr';
            const listContainer = document.getElementById('relatedSkillsList');
            const section = document.getElementById('relatedSkillsSection');

try {
                const response = await fetch(`/api/related-skills/${encodeURIComponent(owner)}/${encodeURIComponent(skillName)}?limit=6`);
                
                if (!response.ok) {
                    throw new Error('Failed to load');
                }

const data = await response.json();
                const relatedSkills = data.related_skills || [];

if (relatedSkills.length === 0) {
                    // 没有相关推荐时隐藏整个区域
                    section.style.display = 'none';
                    return;
                }

// 渲染相关 Skills
                listContainer.innerHTML = relatedSkills.map(skill => {
                    const desc = skill.description || '';
                    const truncatedDesc = desc.length > 60 ? desc.substring(0, 60) + '...' : desc;
                    return `
                        <a href="${currentLang === 'en' ? '' : '/' + currentLang}/skill/${skill.owner}/${skill.repo}/${skill.skill_name}" class="related-card">
                            <div class="related-name">${escapeHtml(skill.skill_name)}</div>
                            <div class="related-meta">
                                <span class="related-owner">${escapeHtml(skill.owner)}</span>
                                <span class="related-installs">${skill.installs}</span>
                            </div>
                            <div class="related-desc">${escapeHtml(truncatedDesc)}</div>
                        </a>
                    `;
                }).join('');

} catch (error) {
                console.error('Failed to load related skills:', error);
                // 加载失败时显示提示或隐藏
                listContainer.innerHTML = '<div class="related-empty">暂无相关推荐</div>';
            }
        }

// HTML 转义
        function escapeHtml(text) {
            const div = document.createElement('div');
            div.textContent = text;
            return div.innerHTML;
        }

// 页面加载完成后异步加载相关 Skills
        if (document.readyState === 'loading') {
            document.addEventListener('DOMContentLoaded', loadRelatedSkills);
        } else {
            loadRelatedSkills();
        }
    </script>

</body>
</html>

安装

Users

Dashboard

Dashboard