Retour • 13/02/2025

NuQS : Comment gérer l'état de ton URL en NextJS

Écris par Melvyn Malherbe le 13/02/2025

Tu as déjà eu besoin de synchroniser l'état de ton application avec l'URL ? Par exemple, pour gérer des filtres, une pagination ou même un système de recherche ? C'est exactement ce que permet de faire NuQS, une librairie qui va révolutionner ta façon de gérer l'état dans tes URLs.

C'est quoi NuQS ?

NuQS est une librairie qui te permet de synchroniser l'état de ton application avec les paramètres de l'URL (query parameters). C'est comme un useState, mais au lieu de stocker la valeur en mémoire, elle est stockée dans l'URL.

Imagine que tu as un composant de recherche :

'use client'

import { useQueryState } from 'nuqs'

export function SearchComponent() {
  const [search, setSearch] = useQueryState('q')
  
  return (
    <div>
      <input 
        value={search || ''} 
        onChange={e => setSearch(e.target.value)} 
        placeholder="Rechercher..."
      />
      <p>Recherche en cours : {search || 'aucune'}</p>
    </div>
  )
}

Quand l'utilisateur tape quelque chose, l'URL se met automatiquement à jour avec ?q=valeur. L'avantage ? L'état est persistant dans l'URL, ce qui permet de :

• Partager l'URL avec les filtres
• Revenir en arrière avec le bouton précédent du navigateur
• Rafraîchir la page en gardant les filtres

Quand utiliser NuQS ?

NuQS est particulièrement utile dans plusieurs cas :

1. Filtres et tris : Pour gérer les filtres d'une liste de produits, articles ou autres données.

'use client'

import { useQueryStates, parseAsInteger, parseAsString } from 'nuqs'

export function ProductFilters() {
  const [filters, setFilters] = useQueryStates({
    category: parseAsString.withDefault('all'),
    price: parseAsInteger.withDefault(0),
    sort: parseAsString.withDefault('newest')
  })

  return (
    <div>
      <select 
        value={filters.category} 
        onChange={e => setFilters({ category: e.target.value })}
      >
        <option value="all">Toutes les catégories</option>
        <option value="electronics">Électronique</option>
        <option value="books">Livres</option>
      </select>
      {/* Autres filtres... */}
    </div>
  )
}

2. Pagination : Pour gérer la page courante et le nombre d'éléments par page.

3. État de l'interface : Pour sauvegarder l'état d'ouverture/fermeture des panneaux, les onglets actifs,

4. État de l'interface : Pour sauvegarder l'état d'ouverture/fermeture des panneaux, les onglets actifs, etc.

NuQS côté serveur

L'un des plus gros avantages de NuQS, c'est qu'il fonctionne parfaitement avec les Server Components de Next.js. Tu peux récupérer les valeurs des paramètres directement côté serveur :

import { parseAsInteger } from 'nuqs/server'

export default async function ProductPage({ searchParams }: { searchParams: Record<string, string> }) {
  const page = parseAsInteger.withDefault(1)(searchParams.page)
  const limit = parseAsInteger.withDefault(10)(searchParams.limit)
  
  const products = await prisma.product.findMany({
    skip: (page - 1) * limit,
    take: limit,
  })

  return (
    <div>
      <h1>Produits (Page {page})</h1>
      <ProductList products={products} />
      <Pagination currentPage={page} />
    </div>
  )
}

Ce qui est génial avec cette approche, c'est que :

1. Les données sont chargées côté serveur, donc pas de chargement visible
2. Le SEO est parfait car les moteurs de recherche voient directement le contenu
3. L'expérience utilisateur est optimale avec une navigation instantanée

Les bonnes pratiques avec NuQS

Voici quelques conseils pour bien utiliser NuQS :

1. Utilise les parsers : NuQS fournit des parsers pour différents types de données :

import { 
  parseAsInteger,
  parseAsFloat,
  parseAsBoolean,
  parseAsArrayOf,
  parseAsJson
} from 'nuqs'

const [filters] = useQueryStates({
  page: parseAsInteger.withDefault(1),
  active: parseAsBoolean.withDefault(true),
  tags: parseAsArrayOf(parseAsString).withDefault([]),
})

2. Gère les valeurs par défaut : Toujours définir des valeurs par défaut pour éviter les états undefined :

const [sort, setSort] = useQueryState(
  'sort',
  parseAsString.withDefault('newest')
)

3. Optimise pour le SEO : Utilise des noms de paramètres explicites et courts :
   • ✅ ?category=books&sort=price
   • ❌ ?c=b&s=p

Conclusion

NuQS est un excellent choix quand tu as besoin de :

• Partager des états via l'URL
• Gérer la navigation avec l'historique du navigateur
• Optimiser le SEO de tes pages filtrables
• Créer une expérience utilisateur fluide avec Next.js

C'est particulièrement utile pour les applications e-commerce, les blogs avec filtres, ou toute interface où l'état doit être partageable via URL.

Si tu veux approfondir tes connaissances en Next.js, je te conseille de regarder ma formation Next.js où j'explique en détail comment créer des applications modernes et performantes.