NuQS : Comment gérer l'état de ton URL en NextJS
13/02/2025 • Melvynx
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.
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 :
NuQS est particulièrement utile dans plusieurs cas :
"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>
);
}
Pagination : Pour gérer la page courante et le nombre d'éléments par page.
État de l'interface : Pour sauvegarder l'état d'ouverture/fermeture des panneaux, les onglets actifs,
État de l'interface : Pour sauvegarder l'état d'ouverture/fermeture des panneaux, les onglets actifs, etc.
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 :
Voici quelques conseils pour bien utiliser NuQS :
import {
parseAsInteger,
parseAsFloat,
parseAsBoolean,
parseAsArrayOf,
parseAsJson,
} from "nuqs";
const [filters] = useQueryStates({
page: parseAsInteger.withDefault(1),
active: parseAsBoolean.withDefault(true),
tags: parseAsArrayOf(parseAsString).withDefault([]),
});
const [sort, setSort] = useQueryState(
"sort",
parseAsString.withDefault("newest"),
);
?category=books&sort=price
?c=b&s=p
NuQS est un excellent choix quand tu as besoin de :
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.