Quando comecei a construir interfaces com Next.js, sempre esbarrava na mesma dor: sincronizar filtros, buscas e paginação entre componentes, URL e cache de dados. O usuário clicava, a tela mudava, mas a URL não refletia nada — e recarregar a página fazia tudo desaparecer. Foi aí que conheci o nuqs.
O nuqs é uma biblioteca leve que sincroniza o estado da interface com a query string da URL. Ele substitui aquela confusão de estados locais e contextos globais por algo simples: o próprio endereço do navegador.
Isso significa que qualquer mudança de estado (filtros, busca, página atual, tema, etc.) pode ser compartilhada apenas copiando a URL. É como se o estado virasse parte natural da navegação.
Eu costumava criar estruturas complexas com React Context, Redux ou Zustand só para guardar pequenas coisas como “qual aba está aberta” ou “qual filtro está ativo”. O problema é que isso não persiste entre sessões e não reflete na URL, o que é ruim pra UX e pra SEO.
Com o nuqs, percebi que grande parte desse estado era na verdade estado de URL — coisas que deveriam estar visíveis e reproduzíveis. Agora, cada filtro ou página é um link. E isso muda tudo.
Num painel de análise que fiz, existiam filtros de data, empresa e status. Antes, cada um ficava salvo no estado do React e resetava ao recarregar. Com nuqs, fiz assim:
"use client";
import { useQueryState, parseAsString } from "nuqs";
export function Filters() {
const [company, setCompany] = useQueryState(
"company",
parseAsString.withDefault("all")
);
const [status, setStatus] = useQueryState(
"status",
parseAsString.withDefault("active")
);
return (
<div className="flex gap-2">
<select value={company} onChange={(e) => setCompany(e.target.value)}>
<option value="all">Todas</option>
<option value="intrabank">Intrabank</option>
<option value="xesq">Xesq</option>
</select>
<select value={status} onChange={(e) => setStatus(e.target.value)}>
<option value="active">Ativos</option>
<option value="pending">Pendentes</option>
</select>
</div>
);
}
A URL fica assim:
/dashboard?company=intrabank&status=pending
E isso significa que posso mandar esse link no Slack e a outra pessoa vê exatamente a mesma tela que eu. Sem precisar salvar nada no backend, sem estado global, sem gambiarra.
O nuqs virou uma peça central no meu fluxo de front-end com Next.js. Hoje, sempre que vejo um estado que afeta a navegação ou precisa ser compartilhável, já sei: ele pertence à URL.
Mais do que uma biblioteca, o nuqs me ensinou a enxergar o estado da aplicação como parte da navegação — e isso elevou a clareza e simplicidade do meu código a outro nível.