Next.js 15: Cambio crítico de searchParams

Comprendiendo el cambio de objetos síncronos a Promesas en Next.js y cómo migrar tu código al nuevo modelo

Publicado el 21 de octubre de 2024, Next.js 15 llegó con novedades potentes y un cambio que tomó por sorpresa a muchos equipos: searchParams ahora es una Promesa. Si vienes de Next.js 14 y estás planeando actualizar, esta ruptura de compatibilidad exige pequeños ajustes. Aquí encontrarás qué cambió, por qué cambió, cómo migrar de forma segura y cómo aprovechar los beneficios de rendimiento que habilita.

Qué cambió

En Next.js 14, searchParams era un objeto accesible de forma síncrona dentro de los Server Components. En Next.js 15, searchParams es una Promesa que debes resolver con await. En la práctica, tu componente de página debe ser async y necesitas await searchParams antes de leer sus propiedades. Un patrón recomendado es hacer await una vez y luego desestructurar: const params = await searchParams; const { q, page, sort } = params. Evita hacer await repetidos sobre la misma Promesa.

Por qué se introdujo este cambio

Primero, para habilitar streaming y renderizado concurrente a nivel de plataforma, permitiendo que el servidor comience a enviar partes de la interfaz antes de resolver todos los parámetros. Segundo, para mejorar la gestión de recursos y el parsing de URLs complejas en el servidor. Tercero, para alinear el framework con la dirección asíncrona de React y el uso de Suspense en Server Components. Y cuarto, para preparar optimizaciones futuras en el pipeline de renderizado del lado servidor.

Migración paso a paso

1. Marca tus páginas como funciones async. 2. Haz await de searchParams antes de acceder a sus claves y desestructura después del await. 3. Actualiza helpers y utilidades que reciban searchParams para que acepten una Promesa o para que esperen el objeto resuelto internamente. 4. Valida los parámetros de URL con defaults seguros, por ejemplo convertir page a entero mínimo 1, limitar limit a un máximo razonable y normalizar sort a un conjunto permitido. 5. En TypeScript, tipa las props como searchParams: Promise y conserva un índice flexible para claves dinámicas. 6. Añade try catch para manejar posibles errores al resolver la Promesa, devolviendo estados de error amigables. 7. Ajusta tus tests para pasar un Promise.resolve con el objeto de parámetros simulado y para invocar el componente async de forma asíncrona.

Errores comunes y cómo evitarlos

Olvidar el await y tratar searchParams como objeto romperá la ejecución. Usar await dentro de un componente que no es async fallará. Esperar la misma Promesa varias veces incurre en sobrecoste y ruido; espera una vez, guarda el resultado y reutilízalo. Si pasas searchParams a un hijo Server Component, puedes pasar la Promesa y resolverla allí, protegida por un Suspense si lo necesitas. Recuerda que en Client Components el patrón recomendado sigue siendo el hook useSearchParams de next/navigation, que se mantiene orientado al cliente.

Buenas prácticas

Haz await una sola vez y desestructura. Centraliza el parseo en una función reutilizable que convierta page, limit y filtros a tipos primitivos válidos y con valores por defecto. Valida whitelists para sort y evita inyecciones en consultas. Utiliza Promise.all para resolver en paralelo searchParams y otros datos del servidor. Añade límites y normalizaciones numéricas. Separa la resolución de searchParams del fetching de datos para facilitar tests y reutilización. Considera Suspense para aislar la espera de parámetros en subárboles específicos y favorecer el streaming de encabezado y diseño principal.

Ejemplo conceptual antes y después

Antes en Next.js 14: function Page({ searchParams }) { const q = searchParams.q; const page = parseInt(searchParams.page) || 1; ... }. Después en Next.js 15: async function Page({ searchParams }) { const params = await searchParams; const { q, page: pageParam } = params; const page = Math.max(1, parseInt(pageParam) || 1); ... }. El patrón clave es que todo acceso a propiedades ocurre tras await.

Patrones de validación rápidos

Convierte page a entero mínimo 1. Limita limit con un rango seguro, por ejemplo entre 1 y 50. Asegura sort con una lista de valores permitidos como name price date. Normaliza booleanos desde cadenas a booleanos reales, por ejemplo in_stock igual a true. Limpia arreglos de filtros eliminando entradas vacías.

Rendimiento y streaming

Al ser asíncrono, el árbol puede comenzar a renderizar con layout, cabecera y contenido base mientras se resuelven los parámetros en secciones específicas bajo límites de Suspense. Esto reduce el tiempo a primer byte visual y mejora la percepción de velocidad. Además, puedes resolver en paralelo searchParams y datos de negocio con Promise.all para reducir el tiempo total de respuesta.

TypeScript en pocas líneas

Declara una interfaz SearchParams con claves opcionales y un índice flexible para parámetros adicionales. En las props, usa searchParams: Promise. Tras await, aplica refinamiento de tipos y normalizaciones para garantizar que tu capa de datos reciba valores correctos.

Testing

En pruebas unitarias, crea un mock con Promise.resolve y pásalo como prop searchParams a tu componente de página. Renderiza de forma asíncrona en el entorno de test, verifica que se muestren textos derivados de q, category, page y valida que se apliquen defaults cuando faltan parámetros.

Migración automatizable

Puedes iniciar con una búsqueda por funciones export default function que reciban searchParams y convertirlas a async. Luego introduce una variable intermedia como const params igual a await searchParams y reemplaza accesos directos por params.clave. Apóyate en reglas de ESLint para prevenir await faltantes y en revisiones de tipado para detectar accesos inseguros.

Checklist rápido

Convierte tus páginas a async. Haz await de searchParams una vez y desestructura. Actualiza helpers y tipos. Añade validación y defaults. Usa Promise.all para concurrencia. Cubre con tests y estados de error. Comprueba rutas con múltiples combinaciones de consulta.

Cómo encaja esto en productos reales

En catálogos, listados de blog o buscadores, el patrón asíncrono permite emitir el contenedor y la navegación de inmediato y demorar secciones dependientes de filtros costosos. Al combinarlo con almacenamiento en caché del lado servidor y segmentación por parámetros, se obtienen mejoras tangibles en experiencia y SEO técnico.

Q2BSTUDIO te acompaña

En Q2BSTUDIO somos una empresa de desarrollo de software y aplicaciones a medida, especialistas en inteligencia artificial, ciberseguridad, servicios cloud aws y azure, servicios inteligencia de negocio y power bi, automatización de procesos, agentes IA e ia para empresas. Si necesitas migrar a Next.js 15, optimizar rendimiento o construir una plataforma moderna de extremo a extremo, nuestro equipo puede ayudarte a diseñar, desarrollar y asegurar cada capa de tu solución. Conoce cómo abordamos proyectos de software a medida y multiplataforma en desarrollo de aplicaciones y software a medida o descubre cómo aceleramos casos de uso con modelos, orquestación y agentes en inteligencia artificial para empresas.

Conclusión

El cambio de searchParams a Promesa en Next.js 15 es un paso lógico hacia un modelo de renderizado más eficiente y concurrente. La migración es directa si aplicas tres ideas clave: convierte tus páginas a async, haz await de searchParams y centraliza el parseo y validación. A partir de ahí, podrás habilitar streaming, reducir el tiempo de respuesta percibido y escalar tus vistas con mayor robustez. Recuerda validar y sanear siempre los parámetros de URL, y apóyate en tests para garantizar que tu transición sea segura.

Palabras clave relacionadas: aplicaciones a medida, software a medida, inteligencia artificial, ciberseguridad, servicios cloud aws y azure, servicios inteligencia de negocio, ia para empresas, agentes IA, power bi.