Bonjour à tous, je m'appelle Marie et je suis développeuse full-stack depuis 6 ans. Aujourd'hui, je vais vous guider paso a paso dans l'intégration de réponses IA en streaming avec Next.js App Router et la technologie SSE (Server-Sent Events). Si vous êtes débutant complet, ne vous inquiétez pas — je pars de zéro et j'explique chaque concept simplement.

Qu'est-ce que le streaming SSE et pourquoi c'est magique ?

Imaginez que vous utilisez ChatGPT ou Claude et que vous voyez le texte s'afficher lettre par lettre, comme si quelqu'un tapait en temps réel. C'est exactement ce que permet le streaming SSE !

Contrairement à une réponse classique où le serveur attend d'avoir TOUTE la réponse avant de l'envoyer (ça peut prendre 10-30 secondes), le streaming envoie chaque petit morceau dès qu'il est disponible. Avec HolySheep AI, notre latence moyenne est inférieure à 50ms, ce qui rend l'expérience utilisateur incroyablement fluide.

Ce dont vous avez besoin avant de commencer

Étape 1 : Créer votre projet Next.js

Ouvrez votre terminal et tapez cette commande. Ne vous inquiétez pas, je vous explique chaque partie après !

npx create-next-app@latest mon-chat-ia

Répondez aux questions ainsi :


- TypeScript : Yes (recommandé)


- ESLint : Yes


- Tailwind CSS : Yes


- src/ directory : Yes


- App Router : Yes (très important!)


- Customize import alias : No (@/*)

Ensuite, entrez dans votre dossier et installez le client HTTP dont nous aurons besoin :

cd mon-chat-ia
npm install openai

Étape 2 : Configurer votre clé API HolySheep

Créez un fichier .env.local à la racine de votre projet (dans le même dossier que package.json) :

# Contenu du fichier .env.local
HOLYSHEEP_API_KEY=YOUR_HOLYSHEEP_API_KEY

⚠️ Important : Remplacez YOUR_HOLYSHEEP_API_KEY par votre vraie clé que vous trouverez dans votre tableau de bord HolySheep. Cette clé est secrète — ne la montrez jamais à personne !

Étape 3 : Créer l'API Route pour le streaming

Dans Next.js App Router, les API routes se trouvent dans src/app/api/. Créez ce fichier :

// src/app/api/chat/route.ts
import { OpenAI } from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.holysheep.ai/v1',
  apiKey: process.env.HOLYSHEEP_API_KEY,
});

export async function POST(request: Request) {
  const { messages } = await request.json();

  const stream = await client.chat.completions.create({
    model: 'gpt-4.1',
    messages: messages,
    stream: true,
  });

  return new Response(stream.toReadableStream(), {
    headers: {
      'Content-Type': 'text/event-stream',
      'Cache-Control': 'no-cache',
      'Connection': 'keep-alive',
    },
  });
}

Étape 4 : Créer le composant React pour le chat

Maintenant, créons l'interface utilisateur. Dans src/app/page.tsx, remplacez tout le contenu par :

'use client';

import { useState } from 'react';

interface Message {
  role: 'user' | 'assistant';
  content: string;
}

export default function ChatPage() {
  const [messages, setMessages] = useState([]);
  const [input, setInput] = useState('');
  const [isLoading, setIsLoading] = useState(false);

  const sendMessage = async () => {
    if (!input.trim() || isLoading) return;

    const userMessage: Message = { role: 'user', content: input };
    setMessages(prev => [...prev, userMessage]);
    setInput('');
    setIsLoading(true);

    try {
      const response = await fetch('/api/chat', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          messages: [...messages, userMessage]
        }),
      });

      const reader = response.body?.getReader();
      const decoder = new TextDecoder();
      let assistantMessage = '';

      if (reader) {
        while (true) {
          const { done, value } = await reader.read();
          if (done) break;
          
          const chunk = decoder.decode(value);
          assistantMessage += chunk;
          setMessages(prev => {
            const lastMsg = prev[prev.length - 1];
            if (lastMsg?.role === 'assistant') {
              return [...prev.slice(0, -1), { ...lastMsg, content: assistantMessage }];
            }
            return [...prev, { role: 'assistant', content: assistantMessage }];
          });
        }
      }
    } catch (error) {
      console.error('Erreur:', error);
      alert('Une erreur est survenue. Vérifiez votre clé API.');
    } finally {
      setIsLoading(false);
    }
  };

  return (
    <div className="max-w-2xl mx-auto p-4">
      <h1 className="text-2xl font-bold mb-4">Chat IA Streaming</h1>
      <div className="border rounded-lg p-4 h-96 overflow-y-auto mb-4">
        {messages.map((msg, i) => (
          <div key={i} className={msg.role === 'user' ? 'text-blue-600' : 'text-green-600'}>
            <strong>{msg.role === 'user' ? 'Vous' : 'IA'} :</strong> {msg.content}
          </div>
        ))}
        {isLoading && <div className="text-gray-500">L'IA écrit...</div>}
      </div>
      <div className="flex gap-2">
        <input
          type="text"
          value={input}
          onChange={(e) => setInput(e.target.value)}
          onKeyDown={(e) => e.key === 'Enter' && sendMessage()}
          placeholder="Tapez votre message..."
          className="flex-1 border p-2 rounded"
        />
        <button
          onClick={sendMessage}
          disabled={isLoading}
          className="bg-blue-600 text-white px-4 py-2 rounded disabled:bg-gray-400"
        >
          Envoyer
        </button>
      </div>
    </div>
  );
}

Étape 5 : Lancer et tester

npm run dev

Ouvrez votre navigateur à l'adresse http://localhost:3000. Tapez un message et observez les caractères apparaître progressivement ! 🎉

Comprendre le flux de données

Voici ce qui se passe quand vous envoyez un message (c'est comme un jeu de passes de ballon) :

Les avantages HolySheep que j'ai découverts

Dans mon expérience pratique avec plusieurs fournisseurs d'API IA, HolySheep m'a vraiment impressionnée. Voici pourquoi :

Optimisation pour la production

Quand votre application sera populaire, vous voudrez améliorer les performances. Voici quelques conseils que j'utilise en production :

// Ajoutez un timeout et une gestion d'erreur robuste
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 60000);

try {
  const response = await fetch('/api/chat', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ messages }),
    signal: controller.signal,
  });
  
  if (!response.ok) {
    throw new Error(HTTP ${response.status});
  }
  // ... traitement du stream
} catch (error) {
  if (error.name === 'AbortError') {
    console.log('Requête annulée (timeout)');
  } else {
    console.error('Erreur:', error);
  }
} finally {
  clearTimeout(timeout);
}

Erreurs courantes et solutions

Erreur 1 : "CORS policy blocked"

Symptôme : Erreur dans la console du navigateur disant que l'accès CORS est bloqué.

Cause : Le navigateur bloque les requêtes depuis localhost vers l'API.

Solution : Modifiez votre route API pour inclure les headers CORS :

// src/app/api/chat/route.ts
export async function POST(request: Request) {
  // ... votre code existant ...
  
  return new Response(stream.toReadableStream(), {
    headers: {
      'Content-Type': 'text/event-stream',
      'Cache-Control': 'no-cache',
      'Connection': 'keep-alive',
      'Access-Control-Allow-Origin': '*',
    },
  });
}

Erreur 2 : "401 Unauthorized"

Symptôme : La réponse HTTP est 401 et vous voyez "Incorrect API key provided".

Cause : Votre clé API n'est pas reconnue ou mal configurée.

Solution : Vérifiez que votre fichier .env.local contient la bonne clé :

# Dans .env.local (sans guillemets autour de la clé)
HOLYSHEEP_API_KEY=sk-holysheep-votre-cle-reelle-ici

Redémarrez le serveur avec npm run dev après toute modification du .env.

Erreur 3 : "stream is not readable"

Symptôme : L'erreur "stream is not readable" apparaît et rien ne s'affiche.

Cause : Le stream a déjà été consommé ou n'est pas correctement converti.

Solution : Utilisez cette approche améliorée pour le client :

const response = await fetch('/api/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ messages }),
});

if (!response.body) {
  throw new Error('Pas de body dans la réponse');
}

const reader = response.body.getReader();
const decoder = new TextDecoder();

// Lisez le stream morceau par morceau
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const text = decoder.decode(value, { stream: true });
  // Traitez chaque morceau ici
  console.log('Reçu:', text);
}

Erreur 4 : Le texte s'accumule au lieu de s'afficher

Symptôme : Chaque mise à jour ajoute le texte précédent au lieu de le remplacer.

Cause : Vous n'annexez pas correctement les nouveaux chunks aux existants.

Solution : Le problème vient souvent du format SSE. Assurez-vous que votre serveur envoie correctement :

// Format SSE correct : chaque chunk doit être formaté ainsi
const chunk = `data: ${JSON.stringify({
  choices: [{ delta: { content: 'nouveau texte' } }]
})}\n\n`;

// OU en texte brut (selon votre configuration)
const textChunk = 'nouveau texte';

Conclusion

Félicitations ! 🎉 Vous venez de créer votre première application Next.js avec des réponses IA en streaming. Les possibilités sont infinies : chatbots, assistants de codage, générateurs de contenu, et bien plus encore.

Ce que j'ai particulièrement apprécié avec cette implémentation, c'est la simplicité du code et la performance exceptionnelle de HolySheep AI. La latence inférieure à 50ms rend l'expérience indistinguishable d'une conversation humaine réelle.

N'hésitez pas à expérimenter avec différents modèles — DeepSeek V3.2 pour les tâches économiques, GPT-4.1 pour les réponses détaillées, ou Gemini 2.5 Flash pour la vitesse maximale.

Prochaines étapes recommandées

👉 Inscrivez-vous sur HolySheep AI — crédits offerts

Bonne chance dans vos développements, et n'hésitez pas à me contacter si vous avez des questions ! 🚀

Ressources connexes