# Sentry et les React Server Components : instrumenter un rendu hybride

> Étapes concrètes pour tracer une erreur qui n'apparaît que côté serveur d'un composant hybride consommant WordPress, avec Sentry et l'App Router de Next.js.

- Auteur : Clément Hadrot
- Publié le : 2025-11-29
- Mis à jour le : 2025-11-29
- Catégorie : Headless & API
- URL : https://wpmoderne.dev.wordpress-developpement.fr/headless/sentry-react-server-components-rendu-hybride/

## L’essentiel

- Configuration Sentry distincte pour le runtime serveur et le runtime client
- Composant serveur enveloppé pour capturer les erreurs de fetch WordPress
- Corrélation via un identifiant de requête transmis de bout en bout

`Error: fetch failed`. Rien de plus, dans les journaux du navigateur, alors que la page affichée à l'écran semblait pourtant complète. C'est le genre de symptôme frustrant que rencontre une équipe qui migre un front WordPress headless vers l'App Router de Next.js et ses React Server Components : une partie du rendu se fait désormais côté serveur, avant même d'atteindre le navigateur, et les outils d'observabilité pensés pour du rendu 100 % client ratent purement et simplement ces erreurs.

Ce tutoriel détaille, étape par étape, comment instrumenter correctement Sentry pour capturer les erreurs qui surviennent exclusivement pendant le rendu serveur d'un composant hybride qui va chercher son contenu auprès de WordPress. La configuration des règles d'alertes Sentry elles-mêmes n'est pas traitée ici : elle mérite un article dédié.

## Étape 1 : comprendre pourquoi le SDK client ne suffit pas

Un React Server Component s'exécute sur le serveur Next.js, jamais dans le navigateur. Si ce composant échoue à récupérer une donnée WordPress via `fetch()`, par exemple parce que l'API REST répond un statut 500, l'erreur se produit avant même que la moindre ligne de JavaScript client ne s'exécute. Le SDK Sentry configuré uniquement pour le navigateur (`@sentry/nextjs` initialisé côté client) ne verra jamais passer cette erreur, puisqu'elle ne traverse jamais l'environnement où il est actif.

## Étape 2 : mettre en place les trois fichiers de configuration Sentry

Le SDK `@sentry/nextjs` attend trois fichiers de configuration distincts, chacun couvrant un runtime différent de l'application : le navigateur, le serveur Node.js, et le runtime Edge si des routes en dépendent.

```
// sentry.server.config.ts
import * as Sentry from '@sentry/nextjs';

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  tracesSampleRate: 0.3,
  environment: process.env.VERCEL_ENV ?? 'development',
});
```

```
// sentry.client.config.ts
import * as Sentry from '@sentry/nextjs';

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  tracesSampleRate: 0.1,
});
```

> L'essentiel à retenir : Configuration Sentry distincte pour le runtime serveur et le runtime client ; Composant serveur enveloppé pour capturer les erreurs de fetch WordPress ; Corrélation via un identifiant de requête transmis de bout en bout

## Étape 3 : envelopper les appels WordPress dans une fonction tracée

Plutôt que d'appeler `fetch()` directement dans chaque composant serveur, il est préférable de centraliser les appels à l'API WordPress dans une fonction unique, elle-même instrumentée pour capturer et enrichir toute erreur avant de la relancer :

```
import * as Sentry from '@sentry/nextjs';

export async function getPost(slug: string) {
  return Sentry.startSpan({ name: 'wp.getPost', op: 'http.client' }, async () => {
    const res = await fetch(`${process.env.WP_API_URL}/posts?slug=${slug}`, {
      next: { revalidate: 60 },
    });

    if (!res.ok) {
      Sentry.captureException(new Error(`WP API ${res.status} sur /posts?slug=${slug}`), {
        tags: { component: 'rsc', endpoint: 'posts' },
      });
      throw new Error('Impossible de charger l\'article');
    }

    return res.json();
  });
}
```

Cette fonction ajoute deux informations précieuses : un *span* de tracing qui apparaît dans le tableau de performance de Sentry, et une capture d'exception enrichie de tags qui permettent, une fois dans l'interface Sentry, de filtrer immédiatement les erreurs provenant du rendu serveur, par opposition à celles survenant côté client.

## Étape 4 : corréler serveur et client avec un identifiant de requête

Un rendu hybride affiche parfois une partie de la page depuis le composant serveur, et une autre partie depuis un composant client qui effectue son propre appel une fois l'hydratation terminée. Pour relier les deux dans Sentry, un identifiant de requête généré côté serveur est transmis au client via une prop, puis rattaché à chaque événement capturé côté navigateur :

```
Sentry.setTag('request-id', requestId);
```

Cette corrélation permet, en cas d'erreur double (une côté serveur, une autre côté client sur la même navigation), de reconstituer immédiatement qu'il s'agit du même incident vécu par le même visiteur, plutôt que de deux événements isolés.

## Étape 5 : vérifier la capture avec une erreur volontaire

1. Couper temporairement l'accès réseau vers l'API WordPress depuis l'environnement de préproduction.
2. Charger une page qui dépend d'un composant serveur consommant cette API.
3. Vérifier dans le tableau de bord Sentry qu'un événement apparaît bien avec le tag `component: rsc`.
4. Confirmer que le *span* associé apparaît dans l'onglet performance, avec une durée cohérente avec le délai de coupure réseau simulé.

> Tant qu'une erreur volontairement provoquée n'apparaît pas dans le tableau de bord, mieux vaut considérer que l'instrumentation n'est pas terminée, quelle que soit la documentation suivie pour la mettre en place.

## Notre verdict

Instrumenter correctement un rendu hybride demande de penser en trois environnements distincts plutôt qu'en un seul : navigateur, serveur Node.js, et éventuellement runtime Edge. Sans cette distinction, une large part des erreurs de récupération de contenu WordPress reste invisible, précisément celles qui surviennent le plus tôt dans le cycle de rendu et qui, souvent, ont le plus d'impact sur ce que voit finalement l'utilisateur.