L'erreur Error: useState can only be used in Client Components ou son équivalent Event handlers cannot be passed to Client Component props apparaît tôt chez quasiment tous les développeurs qui migrent du Pages Router vers l'App Router. La réaction immédiate est d'ajouter 'use client' en haut de chaque fichier qui pose problème, jusqu'à ce que l'application entière redevienne un rendu client classique, ce qui annule l'intérêt même des Server Components. Comprendre la frontière entre les deux modèles évite ce réflexe et permet de concevoir des arborescences de composants qui exploitent vraiment le rendu serveur.

Le modèle mental : deux runtimes, pas deux syntaxes

Dans l'App Router, tout composant est un Server Component par défaut. Un Server Component s'exécute uniquement sur le serveur (ou au build en génération statique), ne s'embarque jamais dans le bundle JavaScript envoyé au navigateur, et peut donc faire des choses impossibles côté client sans détour : await directement une requête base de données ou un appel API avec des secrets, lire le système de fichiers, importer des paquets lourds sans alourdir le bundle.

// app/products/[id]/page.tsx - Server Component par défaut, pas de directive
import { db } from '@/lib/db';

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

  if (!product) {
    return <p>Produit introuvable.</p>;
  }

  return (
    <div>
      <h1>{product.name}</h1>
      <p>{product.description}</p>
      <AddToCartButton productId={product.id} />
    </div>
  );
}

Un Client Component, déclaré avec la directive 'use client' en tête de fichier, s'exécute côté navigateur (après une première passe de rendu serveur pour le HTML initial) et peut donc utiliser useState, useEffect, les écouteurs d'événements, et toute API du navigateur (localStorage, window, géolocalisation).

// app/products/[id]/AddToCartButton.tsx
'use client';

import { useState } from 'react';

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

  async function handleClick() {
    setIsAdding(true);
    await fetch('/api/cart', { method: 'POST', body: JSON.stringify({ productId }) });
    setIsAdding(false);
  }

  return (
    <button onClick={handleClick} disabled={isAdding}>
      {isAdding ? 'Ajout...' : 'Ajouter au panier'}
    </button>
  );
}

Ce n'est pas une question de préférence stylistique : useState ne peut littéralement pas exister dans un composant qui ne s'exécute jamais dans le navigateur, puisque l'état côté client suppose un cycle de rendu et de ré-affichage qui n'a pas de sens côté serveur.

La règle de composition qui évite 90% des erreurs

'use client' marque la frontière à partir de laquelle un sous-arbre entier devient client, mais ne force pas la remontée vers les parents. Autrement dit, un Server Component peut importer et rendre un Client Component (comme ProductPage rend AddToCartButton ci-dessus), mais un Client Component ne peut pas importer un Server Component pour l'exécuter dans son propre contexte - parce qu'au moment où React exécute le code côté client, il n'y a plus de serveur disponible pour produire le rendu de ce Server Component.

L'erreur typique vient de l'intuition inverse :

// Mauvais : CartPanel est 'use client', et essaie d'importer un Server Component
'use client';

import { RecommendedProducts } from './RecommendedProducts'; // Server Component qui fait un fetch DB

export function CartPanel() {
  const [isOpen, setIsOpen] = useState(false);
  return (
    <div className={isOpen ? 'open' : 'closed'}>
      <RecommendedProducts /> {/* ne fonctionnera pas comme attendu */}
    </div>
  );
}

Next.js ne lèvera pas forcément une erreur explicite ici selon le cas, mais RecommendedProducts sera traité comme un composant client ordinaire (il perd ses capacités serveur, ou l'import échoue si le fichier utilise des API serveur comme fs ou un client Prisma). Le correctif consiste à inverser la relation : passer le Server Component en children ou en prop depuis un parent serveur.

// Bon : le parent (Server Component) compose les deux
// app/cart/page.tsx
import { CartPanel } from './CartPanel';
import { RecommendedProducts } from './RecommendedProducts';

export default function CartPage() {
  return (
    <CartPanel>
      <RecommendedProducts />
    </CartPanel>
  );
}
// CartPanel.tsx
'use client';

export function CartPanel({ children }: { children: React.ReactNode }) {
  const [isOpen, setIsOpen] = useState(false);
  return <div className={isOpen ? 'open' : 'closed'}>{children}</div>;
}

children est ici un "trou" dans l'arbre client, déjà rendu en HTML serveur, que le Client Component se contente d'afficher sans jamais exécuter son code. C'est le pattern central pour garder un Server Component en profondeur dans un arbre par ailleurs interactif.

Où tracer la frontière dans une vraie page

La question à se poser composant par composant n'est pas "est-ce que ce composant affiche des données" mais "ce composant a-t-il besoin d'interactivité navigateur (state, effect, event handler, API navigateur) ou d'un contexte React (useContext) alimenté par un Provider client ?". Si non, il reste Server Component par défaut, même s'il reçoit des props complexes.

Un pattern fréquent sur une page de type dashboard :

// Server Component : récupère les données, pas d'interactivité
export default async function DashboardPage() {
  const stats = await getStats();
  return (
    <section>
      <StatsSummary stats={stats} />      {/* Server Component : juste de l'affichage */}
      <StatsChart data={stats.timeline} /> {/* Client Component : bibliothèque de charts interactive */}
    </section>
  );
}

StatsSummary n'a aucune raison d'être client component même s'il affiche des chiffres dynamiques, puisqu'il ne fait que rendre du JSX à partir de props déjà résolues. StatsChart, lui, a probablement besoin de 'use client' parce que la bibliothèque de graphiques (Recharts, Chart.js) manipule le DOM, écoute des événements de survol, et n'a pas de sens exécutée côté serveur.

Les cas limites qui piègent même des devs expérimentés

  • Les hooks tiers non marqués : une bibliothèque qui exporte un hook React sans directive 'use client' dans son propre code cassera si elle est importée dans un Server Component. La solution est d'encapsuler cet import dans un petit Client Component dédié.
  • Context.Provider : un createContext/useContext nécessite que le Provider soit un Client Component. Le pattern courant est un unique Providers.tsx client, monté une fois en haut de l'arbre dans layout.tsx, qui enveloppe children (un Server Component) sans forcer tout le reste en client.
  • Les variables d'environnement : une variable sans préfixe NEXT_PUBLIC_ lue dans un Server Component ne sera jamais exposée au client, ce qui est voulu pour les secrets, mais casse silencieusement si on s'attend à la retrouver après hydratation.
  • Server Actions : une fonction serveur appelée depuis un formulaire client ('use server' dans la fonction, appelée via action={myServerAction}) reste la façon idiomatique de faire des mutations sans passer par une route API dédiée, et mérite d'être préférée à un fetch manuel vers un route.ts quand la mutation est simple.

Quand la frontière Server/Client ne suffit pas comme réponse

Découper correctement Server/Client résout la question "où s'exécute ce code", mais pas celle de la fraîcheur des données. Un Server Component qui fait un fetch sans configuration explicite de cache peut servir des données obsolètes pendant la durée du cache par défaut de Next.js, ce qui surprend souvent en recette. Il faut alors raisonner séparément sur cache: 'no-store', les tags de revalidation (revalidateTag), ou la régénération incrémentale (revalidate), qui sont des décisions indépendantes du choix Server/Client.

À retenir

Server Component est le défaut, Client Component l'exception réservée à ce qui a réellement besoin du navigateur. La règle de composition à retenir est qu'un arbre client peut recevoir un Server Component déjà rendu via children/props, mais ne peut jamais l'importer pour l'exécuter lui-même. Repousser 'use client' le plus bas possible dans l'arbre, composant par composant, garde le maximum de code côté serveur et le bundle client au minimum.