Évolution des Paramètres dans les API Routes Next.js : De la Version 13+ à 15+

Introduction

Next.js a introduit des changements significatifs dans la façon dont les paramètres sont gérés dans les API routes entre les versions 13+ et 15+.

Next.js 13+ : Paramètres Synchrones

Structure Traditionnelle

Dans Next.js 13 et les versions antérieures du App Router, les paramètres étaient accessibles de manière synchrone :

// Next.js 13+
export async function GET(
  request: NextRequest,
  { params }: { params: { filename: string } }
) {
  // Accès direct aux paramètres
  const filename = params.filename;
  
  // Traitement...
}

Caractéristiques de l'Approche 13+

• Accès immédiat : Les paramètres sont disponibles instantanément
• Type simple : params est un objet direct avec des propriétés typées
• Syntaxe concise : Moins de code pour accéder aux valeurs

Exemple Complet Next.js 13+

import { NextRequest, NextResponse } from 'next/server';

export async function GET(
  request: NextRequest,
  { params }: { params: { id: string; category: string } }
) {
  // Utilisation directe
  console.log(`ID: ${params.id}, Category: ${params.category}`);
  
  return NextResponse.json({
    id: params.id,
    category: params.category
  });
}

Next.js 15+ : Paramètres Asynchrones

Nouvelle Structure

À partir de Next.js 15, les paramètres sont maintenant encapsulés dans une Promise :

// Next.js 15+
export async function GET(
  request: NextRequest,
  { params }: { params: Promise<{ filename: string }> }
) {
  // Nécessité d'attendre la résolution
  const { filename } = await params;
  
  // Traitement...
}

Caractéristiques de l'Approche 15+

• Accès asynchrone : Les paramètres doivent être attendus avec await
• Type Promise : params est maintenant une Promise<object>
• Sécurité renforcée : Meilleure gestion des erreurs et de l'état de chargement

Exemple Complet Next.js 15+

import { NextRequest, NextResponse } from 'next/server';

export async function GET(
  request: NextRequest,
  { params }: { params: Promise<{ id: string; category: string }> }
) {
  try {
    // Résolution asynchrone des paramètres
    const { id, category } = await params;
    
    console.log(`ID: ${id}, Category: ${category}`);
    
    return NextResponse.json({ id, category });
  } catch (error) {
    return NextResponse.json(
      { error: 'Invalid parameters' },
      { status: 400 }
    );
  }
}

Comparaison Côte à Côte

Aspect	Next.js 13+	Next.js 15+
Type de params	{ filename: string }	Promise<{ filename: string }>
Accès	params.filename	const { filename } = await params
Gestion d'erreur	Aucune protection intégrée	Gestion native avec try/catch
Performance	Synchrone, immédiat	Asynchrone, optimisé
Sécurité de type	Basique	Renforcée avec Promise

Raisons du Changement

1. Cohérence avec l'Architecture Asynchrone

Next.js 15+ aligne la gestion des paramètres avec son architecture entièrement asynchrone, offrant une expérience de développement plus cohérente.

2. Meilleure Gestion des Erreurs

L'approche Promise permet une gestion plus robuste des cas où les paramètres pourraient être invalides ou manquants.

3. Optimisations Futures

Cette structure prépare le terrain pour des optimisations futures, notamment en matière de streaming et de rendu conditionnel.

4. Sécurité de Type Améliorée

TypeScript peut mieux inférer et valider les types avec l'approche Promise.

Guide de Migration

Étapes de Migration

1. Identifier les API routes utilisant l'ancienne syntaxe
2. Modifier la signature de type pour inclure Promise<>
3. Ajouter await avant l'accès aux paramètres
4. Implémenter la gestion d'erreur appropriée

Avant (Next.js 13+)

export async function GET(
  request: NextRequest,
  { params }: { params: { slug: string } }
) {
  const data = await fetchData(params.slug);
  return NextResponse.json(data);
}

Après (Next.js 15+)

export async function GET(
  request: NextRequest,
  { params }: { params: Promise<{ slug: string }> }
) {
  try {
    const { slug } = await params;
    const data = await fetchData(slug);
    return NextResponse.json(data);
  } catch (error) {
    return NextResponse.json(
      { error: 'Invalid parameters' },
      { status: 400 }
    );
  }
}

Validation des Paramètres

Pensez à valider quand même le type params que vous recevez ça vous évitera/affichera mieux les erreurs.

export async function GET(
  request: NextRequest,
  { params }: { params: Promise<{ id: string }> }
) {
  try {
    const { id } = await params;
    
    // Validation
    if (!id || typeof id !== 'string') {
      return NextResponse.json(
        { error: 'ID parameter is required' },
        { status: 400 }
      );
    }
    
    // Traitement...
  } catch (error) {
    return NextResponse.json(
      { error: 'Invalid parameters' },
      { status: 400 }
    );
  }
}

3. Destructuration Propre

// Recommandé
const { filename, category, id } = await params;

// Éviter
const params_resolved = await params;
const filename = params_resolved.filename;

Cas d'Usage Avancés

Paramètres Multiples avec Validation

export async function GET(
  request: NextRequest,
  { params }: { params: Promise<{ 
    userId: string;
    postId: string;
    commentId?: string;
  }> }
) {
  try {
    const { userId, postId, commentId } = await params;
    
    // Validation des paramètres requis
    if (!userId || !postId) {
      return NextResponse.json(
        { error: 'userId and postId are required' },
        { status: 400 }
      );
    }
    
    // Logique avec paramètres optionnels
    const data = commentId 
      ? await getComment(userId, postId, commentId)
      : await getPost(userId, postId);
    
    return NextResponse.json(data);
  } catch (error) {
    return NextResponse.json(
      { error: 'Invalid request' },
      { status: 500 }
    );
  }
}

Impact sur les Performances

Next.js 13+

• Avantage : Accès immédiat aux paramètres
• Inconvénient : Pas de protection contre les paramètres invalides

Next.js 15+

• Avantage : Gestion d'erreur intégrée, meilleure sécurité
• Coût : Overhead minimal dû à l'await (négligeable en pratique)

Conclusion

Bah voilà c'est tout, si vous êtes resté bloqué dans la maj de vos ancien projets comme des vieilles bouses ( comme moi ), maintenant vous savez comment gérer le problème.