pproenca/nuqs

¿Qué hace nuqs?

Prácticas recomendadas para nuqs (estado de consulta de URL con tipado seguro) en Next.js y otros frameworks de React. Esta habilidad debe utilizarse al escribir, revisar o refactorizar código que use nuqs para la gestión de estado en la URL. Se activa en tareas que involucran useQueryState, useQueryStates, parámetros de búsqueda, estado de URL, parámetros de consulta, parsers de nuqs, limitUrlUpdates, Standard Schema, NuqsAdapter o enrutamiento de Next.js con estado.

Descripción general

nuqs simplifica la sincronización del estado de la aplicación con los parámetros de consulta de la URL, proporcionando una API tipada y predecible. Esto permite compartir enlaces con estado persistente, mejorar la navegación y mantener la coherencia entre componentes.

Plataformas compatibles

• Next.js (App Router y Pages Router)
• React Router
• Cualquier framework React que admita manipulación de la URL

Activación

El skill se activa automáticamente cuando se detectan:

• Uso de useQueryState o useQueryStates
• Referencias a searchParams, URLSearchParams o parámetros de consulta
• Configuración de parsers (por ejemplo, parseAsString, parseAsInteger, parseAsJson)
• Opción limitUrlUpdates
• Integración con Standard Schema o NuqsAdapter
• Enrutamiento de Next.js con estado de URL

Prácticas recomendadas

1. Definir parsers con tipos explícitos

import { parseAsString, useQueryState } from 'nuqs'

// Correcto: parser con tipo explícito
const [search, setSearch] = useQueryState('search', parseAsString.withDefault(''))

2. Usar limitUrlUpdates para evitar cambios frecuentes

const [search, setSearch] = useQueryState('search', {
  ...options,
  limitUrlUpdates: 200 // Actualiza la URL cada 200ms
})

3. Integrar con Standard Schema para validación

import { z } from 'zod'
import { createParser } from 'nuqs'

const schema = z.string().min(1).max(50)

const parser = createParser({
  parse: (value) => {
    const result = schema.safeParse(value)
    return result.success ? result.data : null
  },
  serialize: (value) => value
})

4. Usar NuqsAdapter para frameworks sin integración nativa

import { NuqsAdapter } from 'nuqs/adapters/react-router'

function App() {
  return (
    <NuqsAdapter>
      <YourApp />
    </NuqsAdapter>
  )
}

5. Evitar mutación directa de searchParams

Siempre usa los setters proporcionados por useQueryState o useQueryStates en lugar de manipular directamente URLSearchParams.

Ejemplos

Ejemplo básico con useQueryState

'use client'

import { useQueryState } from 'nuqs'

export function SearchBox() {
  const [search, setSearch] = useQueryState('q')
  
  return (
    <input
      value={search ?? ''}
      onChange={(e) => setSearch(e.target.value || null)}
      placeholder="Buscar..."
    />
  )
}

Múltiples estados con useQueryStates

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

const [filters, setFilters] = useQueryStates({
  search: parseAsString.withDefault(''),
  page: parseAsInteger.withDefault(1),
  limit: parseAsInteger.withDefault(10)
})

Recursos adicionales

• Documentación oficial de nuqs
• Repositorio en GitHub