Hoy las herramientas de IA (Claude, ChatGPT, Cursor, Gemini, Copilot) ya forman parte integral de nuestro trabajo. La velocidad de desarrollo ha crecido exponencialmente, pero, para ser franco, tengo la impresión de que la calidad final de los servicios no ha avanzado al mismo ritmo. Cada vez es más habitual encontrarnos con tantos errores nuevos como funcionalidades añadidas, y también escuchar: «No sé por qué esto terminó así».

Cuando desarrollamos con tanta rapidez, dejamos de examinar el código línea por línea con el mismo detenimiento. Precisamente por eso, considero aún más necesario contar con los fundamentos necesarios para orientar a la IA en la dirección correcta. Para mantener la calidad del resultado, debemos ser capaces de detectar los problemas del código generado por la IA y volver a guiarla hacia el objetivo deseado. Entre esos fundamentos se encuentran el desarrollo desde la perspectiva del dominio, la abstracción, el TDD (Test-Driven Development, desarrollo guiado por pruebas), el uso adecuado de librerías y la optimización del rendimiento.

Sin embargo, cada vez que pregunto a colegas de frontend y de otras áreas de TI «¿cuál es la tarea más difícil del desarrollo frontend?», la respuesta más frecuente es siempre la misma: «Gestionar el flujo del estado».

En este artículo trataré de explicar por qué gestionar el flujo del estado resulta tan difícil y qué criterio e intuición conviene desarrollar para hacerlo bien.

¿Qué es el estado (State)?

Antes de entrar de lleno en el tema, empecemos por la pregunta más básica: ¿qué es exactamente eso que llamamos «estado»?

Mientras estudiaba desarrollo frontend, solía leer artículos de hoseung.me. Allí se define el estado como «todos los datos que pueden afectar a la UI». El número de «me gusta», los productos del carrito, si un modal está abierto, los valores introducidos, la información del usuario autenticado, la pestaña seleccionada, los resultados de búsqueda o el estado de carga: todo eso es estado.

La documentación oficial de React ofrece una definición algo más formal. El propio título de la página es "State: A Component's Memory", que podríamos desarrollar como «el mecanismo mediante el cual un componente retiene datos entre renderizados y hace que React dispare un nuevo renderizado cuando esos datos se actualizan». Es decir, son datos que no desaparecen con el paso del tiempo, que se actualizan a raíz de algún evento y que, al hacerlo, provocan que la UI vuelva a dibujarse. Hay otro punto importante: el estado está aislado en cada instancia del componente. Aunque haya diez instancias del mismo componente en una página, cada una conserva su propio estado independiente. Este hecho se relaciona directamente con la cuestión que veremos más adelante: «¿dónde debe residir el estado?».

Ambas definiciones apuntan a lo mismo: el estado es «un valor que cambia con el tiempo y afecta al renderizado». Una constante que no cambia no es estado. Un token de diseño primitivo fijado en build time no es estado, mientras que el modo oscuro que activa o desactiva el usuario sí lo es. (En rigor, el valor se resuelve según el estado del tema oscuro o claro; por tanto, es más preciso considerar que la «selección del tema» es el estado y que el token es el espejo en el que ese estado se refleja).

Conviene señalar algo más: no todo el estado vive en los componentes. Parte vive en cookies; otra, en localStorage, sessionStorage o IndexedDB; y otra, en la URL. Cuando traemos al cliente datos que residen en el servidor y los almacenamos en caché, también se convierten en una forma de estado. Incluso la posición de scroll o el stack del historial que mantiene el navegador deben tratarse a veces como estado, porque determinan el comportamiento de nuestra aplicación.

¿Por qué es tan difícil?

Pensemos primero en términos sencillos por qué cuesta tanto manejar el estado. ¿No bastaría con crear el estado necesario, llevarlo hasta donde haga falta y gestionar bien sus actualizaciones y su reinicialización?

Con esta pregunta en mente, abramos una página del servicio en el que estamos trabajando.

¿Cuántos componentes contiene? Incluso una página sencilla puede tener desde decenas hasta cientos de componentes organizados en forma de árbol. Cada componente puede mantener su propio estado, compartirlo con componentes hermanos o recibirlo de su padre. El estado también se transfiere entre páginas; parte debe sobrevivir a una recarga y parte debe desaparecer al cerrar la pestaña.

La verdadera razón por la que el estado es difícil de gestionar es esta: no podemos ver de un vistazo dónde se declaran todos esos estados, cómo se actualizan ni cuándo desaparecen. Cuantos más componentes con funciones similares aparecen, más difícil resulta nombrar el estado y rastrear el código que lo modifica.

Así se forma una telaraña invisible. Un clic en el componente A invalida los datos de B; esa invalidación cierra la UI de C; y al cerrarse C desaparece el contenido de un formulario. Si esta cadena no está expresada explícitamente en ninguna parte del código, cuando depuramos un error tenemos que reconstruir la telaraña en nuestra cabeza.

Entonces, ¿cómo podemos ordenar esa telaraña? A mi juicio, el primer paso consiste en reconocer que «existen distintos tipos de estado».

No todos los estados son iguales

Kent C. Dodds divide el estado entre Server Cache (información que reside en el servidor y que el cliente conserva para acceder a ella rápidamente) y UI State (estado que solo existe en la UI para controlar el comportamiento de la interfaz). A menudo cometemos errores al agrupar ambos.

La documentación oficial de TanStack Query lo define como una librería de server-state que gestiona operaciones asíncronas entre el servidor y el cliente, mientras que herramientas como Redux, MobX y Zustand son librerías de client-state. (Aunque pueden almacenar datos asíncronos, hacerlo resulta ineficiente).

La idea central es clara: Server State y Client State son problemas distintos. Server State es asíncrono, puede ser modificado por otros usuarios y, con el tiempo, pasa a estar stale. Client State es síncrono, está bajo nuestro control y desaparece al recargar la página. (Para ser exactos, cuando la página se descarga, el runtime de JavaScript se reinicia y tanto el árbol de componentes como el estado alojado en la memoria heap son liberados. Por eso, al montarse de nuevo, useState vuelve a comenzar desde su valor inicial). Si intentamos gestionar ambos con la misma herramienta, tendremos que implementar por nuestra cuenta patrones como la invalidación de caché, la actualización en background o las actualizaciones optimistas.

Doy un paso más y clasifico el estado del frontend en siete categorías. Conviene aclarar de antemano que estas siete categorías no se separan limpiamente sobre un único eje. Mezclan ubicación de almacenamiento, origen, ciclo de vida y función, por lo que un mismo estado puede pertenecer a varias categorías a la vez. No pretenden ser una taxonomía perfecta, sino preguntas que debemos plantearnos al decidir cómo gestionar el estado.

• Estado local (Local State) — Estado usado solo dentro de un componente o de un subárbol reducido
• Estado global (Global State) — Estado que debe compartirse en toda la aplicación
• Estado del servidor (Server State) — Estado cuya fuente de verdad es el servidor y cuya copia en el cliente es una caché
• Estado del formulario (Form State) — Estado temporal que existe mientras el usuario introduce datos
• Estado de la URL (URL State) — Estado compartible que vive en la barra de direcciones y sobrevive a una recarga
• Estado externo (External State) — Estado fuera de React, como cookies, localStorage, sessionStorage e IndexedDB
• Guard de estado (State Guard) — Lógica que bloquea, permite o valida accesos y acciones según combinaciones de estado, en lugar de ser estado por sí misma

Además, existen estados de flujo que conviene modelar con una máquina de estados y estados colaborativos en tiempo real basados en WebSocket o CRDT.

Veamos, una por una, por qué cada categoría requiere herramientas diferentes y con qué criterio debemos abordarla.

Estado local (Local State)

Es el tipo de estado más sencillo. Solo se utiliza dentro de un componente y, desde fuera, no hay necesidad ni motivo para conocerlo. Algunos ejemplos son si un modal está abierto, el estado on/off de un botón toggle, el estado de hover o el término de búsqueda que se está escribiendo.

function SearchBox() {
  const [query, setQuery] = useState("");
  return <input value={query} onChange={(e) => setQuery(e.target.value)} />;
}

Hasta aquí, probablemente todo resulte familiar. Sin embargo, la verdadera dificultad del estado local reside en decidir «dónde debe ubicarse este estado».

En su artículo sobre State Colocation, Kent C. Dodds señala que la gente está acostumbrada a «elevar» el estado (lift up), pero rara vez vuelve a «colocarlo cerca» (colocate) cuando el código cambia.

Elevar el estado es algo que hacemos de forma natural cuando varios componentes hermanos necesitan compartirlo. Como ambos deben ver los mismos datos, trasladamos el estado al padre común y lo pasamos hacia abajo mediante props.

El problema aparece cuando esos componentes hermanos dejan de necesitarlo. No solemos volver a bajar el estado hacia los hijos. Como resultado, el componente padre termina acumulando estados que en realidad no le conciernen y, cada vez que vuelve a renderizarse, todo el árbol de hijos se renderiza con él.

Por eso, el primer criterio para el estado local es: para ganar velocidad y simplicidad, coloca el estado tan cerca como sea posible del código que lo utiliza. Si un estado solo se usa en uno de los hijos de un componente, no hay razón para que lo mantenga el padre. Movámoslo al interior de ese hijo. El padre será más ligero.

Estado global (Global State)

El estado global debe ser accesible desde cualquier parte de la aplicación. La información de autenticación, el tema, el idioma o las notificaciones (toasts) son posibles candidatos.

La diferencia entre el estado local y el global no se reduce a «dónde viven». Lo que cambia es el contrato de acceso. El estado local establece el contrato de que «solo tiene sentido dentro de este componente»; el global, en cambio, publica en todo el código el contrato de que «este valor puede consultarse con este nombre desde cualquier lugar de la aplicación». La esencia del estado global es que ese contrato resulta costoso.

Crear un estado global equivale, en realidad, a añadir una dependencia implícita en toda la aplicación.

Estado del servidor (Server State)

Guardamos en el estado del cliente los datos recibidos mediante una API, gestionamos manualmente la carga y los errores con valores boolean y terminamos preguntándonos: «¿por qué escribo siempre el mismo boilerplate?».

Tanner Linsley, principal responsable de TanStack, afirma: «Client State es síncrono y predecible. Server State es asíncrono, se comparte entre varios componentes y exige gestionar con cuidado el caching, las actualizaciones en background y los estados de error». Es decir, Server State es una especie esencialmente distinta de Client State. No deben tratarse con la misma herramienta.

La complejidad de Server State no se debe a las herramientas, sino a la propia naturaleza de los datos.

Los datos que ve el cliente pertenecen al servidor. Lo que conserva el cliente no es más que un snapshot de un momento concreto. Con el paso del tiempo, esos datos acumulan staleness. Además, son asíncronos, pueden fallar y atraviesan estados como pending, error y success.

La propiedad esencial más importante es que nada garantiza que las respuestas regresen en el mismo orden en que se enviaron las solicitudes. Imaginemos que escribimos rápidamente «react» en un campo de búsqueda. Las solicitudes r → re → rea → reac → react se envían en ese orden, pero si la respuesta de «react» llega primero y después llega la de «rea», la pantalla mostrará los resultados de «rea». Para evitar este problema hay que ocuparse de los riesgos de concurrencia (race conditions), implementando cada vez a mano un AbortController o el seguimiento de los ID de solicitud.

Estado de formulario (Form State)

Los formularios albergan un tipo de estado peculiar. Mientras el usuario escribe, cambia intensamente; pero, una vez enviado, normalmente desaparece. No se comparte con ningún otro lugar y, en la mayoría de los casos, tampoco tiene otro destino en el que almacenarse.

El problema es que ese «cambio intenso» resulta costoso. Si cada pulsación provoca un nuevo renderizado de React, en los formularios grandes el retraso al escribir puede llegar a ser perceptible. Además, un formulario no se limita a «guardar valores». Dentro de él conviven y cambian al mismo tiempo muchos tipos de estado: validación, dirty check, estado de envío, mensajes de error y flujos de varios pasos.

En un formulario de varios pasos, como un proceso de pago en tres etapas, se espera que «el progreso sobreviva incluso a una recarga a mitad del proceso». Si mantenemos los valores del formulario únicamente con useState, la recarga los eliminará todos. Lo natural es almacenarlos en sessionStorage (persistencia temporal por pestaña) o en la URL (para pasos que puedan compartirse). Es decir, según los requisitos de su ciclo de vida, Form State se combina con External State o URL State.

Estado de URL (URL State)

Supongamos que en una página de búsqueda estamos filtrando por categoría, orden y número de página. Si mantenemos esos estados con useState, aparecen tres problemas a la vez.

• Al recargar, todos los filtros se reinician
• Aunque compartamos la URL con otra persona, esta verá la página sin los filtros aplicados
• Al pulsar «Atrás», no regresaremos a los filtros anteriores

Para resolver estos problemas, resulta natural colocar el estado en la URL. La URL es, por sí misma, un almacenamiento persistente gratuito que ya admite recargas, uso compartido e historial.

/products?category=shoes&sort=price-desc&page=2

Esa única línea contiene el estado completo de «la segunda página de la categoría de zapatos, ordenada por precio descendente». No hace falta mantenerlo por separado con useState.

Entonces, ¿cuándo conviene gestionar el estado en la URL? La URL es una interfaz pública. No debemos incluir en ella contraseñas, tokens de autenticación ni notas temporales que el usuario no quiera mostrar a otras personas. Tampoco conviene insertar directamente valores que cambian con demasiada frecuencia —como un término de búsqueda que se actualiza con cada pulsación—, porque el stack del historial se llenará de basura. En esos casos debemos aplicar el cambio después de un debounce y reservar push para cuando corresponda, usando replace en las actualizaciones que no deban añadir una entrada al historial.

Los valores de la URL son siempre strings. Los números, valores boolean, arrays y objetos deben pasar por un proceso de serialización y deserialización. Además, la URL debe seguir las reglas de percent-encoding, por lo que caracteres como &, =, el coreano o los espacios reciben un tratamiento especial. Implementarlo manualmente una y otra vez pronto se convierte en una fuente de errores.

const params = new URLSearchParams(location.search);
const page = Number(params.get("page") ?? "1");
params.set("page", String(page + 1));
navigate(`?${params.toString()}`);
 
const [page, setPage] = useQueryState("page", parseAsInteger.withDefault(1));

Librerías como nuqs resuelven ambos problemas mediante el concepto de parser. Parsers como parseAsInteger, parseAsBoolean y parseAsJson se encargan a la vez de la serialización, la deserialización y los tipos. Son compatibles con la mayoría de los entornos, incluidos Next.js (tanto App Router como Pages Router), React Router v6/v7, TanStack Router y Remix.

¿Significa eso que podemos insertar en la URL todo el estado que queramos? Al margen de los problemas de serialización y tipos, queda una última restricción. RFC 7230 no fija un límite exacto, pero recomienda que «los servidores admitan al menos 8.000 octetos» (unidad que designa inequívocamente un byte formado por ocho bits en redes y comunicaciones de datos). Los límites también varían entre navegadores: los navegadores modernos suelen admitir desde 8 KB hasta decenas de miles de caracteres, pero el procesamiento de OG y enlaces compartidos de buscadores y redes sociales, así como algunos gateways, puede truncarlos alrededor de los 2 KB. Por tanto, no introduzcamos datos ilimitados en la URL. Lo seguro es conservar allí únicamente los filtros esenciales que deban poder compartirse y delegar el resto en sessionStorage o en almacenamiento del lado del servidor.

Estado externo (External State)

React solo conoce el estado que hay en su interior. Sin embargo, nuestra aplicación se comunica sin cesar con el mundo exterior a React. Los estados que viven en ese mundo sobreviven y cambian con independencia del ciclo de vida de React. Aquí, External State se refiere a Cookie, localStorage,sessionStorage,IndexedDB.

¿Cómo elegir el almacenamiento apropiado? Suelo evaluarlo desde cuatro perspectivas: duración, capacidad, sincronía y seguridad.

Para los tokens de autenticación, la recomendación de OWASP prioriza las cookies HttpOnly + Secure. Como JavaScript puede acceder a localStorage, en cuanto se produce una vulnerabilidad XSS, el token queda directamente expuesto. Algunas guías de seguridad recomiendan un patrón híbrido: guardar el access token en memoria y el refresh token en una cookie HttpOnly. Para datos persistentes, no sensibles y que cambian con poca frecuencia se utiliza localStorage; para datos que deben desaparecer junto con la pestaña, sessionStorage. IndexedDB suele emplearse para caché offline, grandes volúmenes de datos y archivos.

Cookie y Web Storage (local/session) solo almacenan strings. Para guardar un objeto hay que pasar por JSON.stringify/JSON.parse. Pero JSON tiene limitaciones.

JSON.stringify({ when: new Date() });
// → { "when": "2026-05-19T..." } — Date becomes a string
 
JSON.stringify({ map: new Map([["a", 1]]) });
// → { "map": {} } — Map is lost entirely
 
JSON.stringify({ value: undefined });
// → "{}" — the undefined field is omitted

Date se convierte en string al hacer un round trip por JSON, mientras que Map, Set y undefined pueden perder datos. Con el comportamiento predeterminado, BigInt hace que JSON.stringify lance un TypeError, por lo que la serialización falla por completo. Al guardar objetos en almacenamiento externo, debemos tener siempre presente qué tipos pueden desaparecer, transformarse o hacer fallar la serialización y añadir un adaptador cuando sea necesario.

La verdadera dificultad de External State es que React no detecta automáticamente sus cambios. Aunque escribamos un valor en localStorage, los componentes de React no vuelven a renderizarse. Normalmente existen tres patrones para resolverlo.

• Envolverlo en un custom hook (useLocalStorage) y sincronizar el estado externo con el estado de React. Es una solución ligera, pero si la implementamos nosotros mismos debemos cubrir todos los casos límite: múltiples pestañas, SSR, tearing, etc.
• Usar el hook useSyncExternalStore, incorporado en React 18, para «sincronizarnos con un estado externo a React». Esto permite garantizar que no se produzca tearing durante el renderizado concurrente. Es la herramienta estándar para conectar localStorage, las API del navegador y los stores externos.
• Aprovechar librerías existentes, ya que las librerías de estado ofrecen como funcionalidad de primera clase la integración con almacenamiento externo, como el middleware persist de Zustand o atomWithStorage de Jotai.

Añadamos otro criterio: en el momento en que llevamos External State a React, la responsabilidad de sincronizarlo recae sobre nosotros. ¿Qué ocurre si se actualiza desde otra pestaña? ¿Si el servidor modifica una cookie? ¿Si el usuario manipula localStorage directamente desde las herramientas de desarrollo del navegador? Estas situaciones suelen convertirse en algunas de las mayores fuentes de errores.

Guard del estado (State Guard)

La última categoría es algo diferente. No es estado en sí mismo, sino la lógica que bloquea, permite o valida un flujo a partir de una combinación de estados.

El ejemplo más habitual es el Auth Guard.

function ProtectedRoute({ children }) {
  const { isAuthenticated, isLoading } = useAuth();
 
  if (isLoading) return <Spinner />;
  if (!isAuthenticated) return <Navigate to="/login" replace />;
  return children;
}

Aquí, el estado isAuthenticated controla el flujo de routing. Eso es precisamente la lógica de un guard. Existen varios tipos: Auth Guard (autenticación), guards de autorización (roles o permisos específicos), guards de flujo (ramificación al entrar) y guards de validación (activación de etapas), entre otros.

La lógica de guards tiende a concentrarse en un único lugar. Es habitual que un componente reúna condiciones como «si no ha iniciado sesión, ir a la página de login; si no tiene permisos, mostrar un 403; si el carrito está vacío, ir a la página de productos; si el usuario está suspendido, mostrar el aviso de suspensión». Cuanto más crece el guard, más difícil resulta depurar qué condición bloqueó el flujo y dónde.

Un buen guard solo comprueba una cosa. La combinación se realiza mediante Composition.

<AuthGuard>
  <RoleGuard role="admin">
    <FlowGuard require={["cartHasItems"]}>
      <CheckoutPage />
    </FlowGuard>
  </RoleGuard>
</AuthGuard>

Cada guard toma una única decisión y la composición queda a cargo de la estructura del árbol. Añadir un guard nuevo no requiere modificar los existentes.

Al diseñar guards, hay algo que debemos pensar incluso más que en el bloqueo: decidir adónde enviar al usuario y qué hacer después. Un guard que solo bloquea y no ofrece fallback termina en una pantalla en blanco o un spinner infinito.

El error más común consiste en que «el contenido protegido parpadea brevemente antes de que termine la comprobación asíncrona del guard». La validación del token de autenticación y la consulta de permisos suelen ser asíncronas; durante ese intervalo, isAuthenticated puede adoptar temporalmente el valor undefined o false. Si no tratamos explícitamente el estado de carga, el contenido protegido puede quedar expuesto durante ese instante o el usuario puede ser redirigido erróneamente a la página de login.

// Ignores loading and handles only missing data => incorrect
if (!user) return <Navigate to="/login" />;
 
// Treat loading as a first-class state (early return) => correct
if (isLoading) return <Spinner />;
if (!user) return <Navigate to="/login" replace />;
return children;

Al implementar guards de autorización se utilizan habitualmente dos modelos.

• RBAC (Role-Based Access Control): asigna permisos por rol. Por ejemplo: «admin puede ver la información de todos los usuarios». Es sencillo y rápido, pero el número de roles se dispara a medida que aumenta la granularidad
• ABAC (Attribute-Based Access Control): determina los permisos mediante una combinación de atributos. Por ejemplo: «si el usuario es autor de la publicación, pertenece al mismo equipo o es admin». Tiene una gran capacidad expresiva, pero es difícil de implementar y depurar

Como muestra la guía de RBAC de TanStack Router, se recomienda el patrón de colocar los guards en beforeLoad, en el nivel del router. La clave es que las comprobaciones de autorización no estén dispersas por el código, sino que puedan expresarse como datos (listas de roles y permisos). Así, un cambio en la política de permisos se limita a un cambio de datos.

Conclusión

Recapitulemos. La gestión del estado no es difícil porque las librerías lo sean. Es difícil porque a menudo olvidamos que existen distintos tipos de estado y porque resulta fácil pasar por alto que cada tipo exige herramientas y formas de pensar diferentes.

Mantener el estado local lo más cerca posible; cuestionar una vez más si el estado global es realmente global; tratar Server State como caché; separar los formularios del dominio; aprovechar la URL de forma más activa; ser conscientes de la responsabilidad que implica el almacenamiento externo; y dividir los guards en unidades pequeñas que puedan componerse. Esos son los fundamentos para trabajar con las siete categorías.

Y el criterio que opera por encima de ellas puede condensarse, en última instancia, en cuatro preguntas.

• ¿Dónde está la Single Source of Truth de estos datos?
• ¿Es un valor que puede calcularse o un valor que realmente debemos almacenar?
• ¿Hay alguna combinación imposible entre estos estados?
• ¿Este estado debe estar realmente en esta ubicación?

Plantearnos estas preguntas cada vez que construimos una pantalla nueva, revisamos una PR o recibimos código generado por la IA es, a mi juicio, la forma más segura de desarrollar criterio e intuición.

Como decía al principio, la IA permanecerá a nuestro lado durante mucho tiempo. Cada vez dedicaremos menos tiempo a revisar el código línea por línea. Pero, precisamente por eso, será más valiosa la capacidad de responder a pequeñas preguntas como «¿dónde debe residir este estado?». Pedirle a la IA «añade aquí otro useState» es fácil. Sin embargo, comprender qué hilo añade esa línea a la telaraña de nuestra aplicación depende únicamente del criterio de quien lee el código.

No existe una única respuesta correcta. Pero hay una diferencia evidente entre «crear estado sin saber qué es el estado» y «crearlo siendo conscientes de su tipo y ubicación». Espero que, la próxima vez que los lectores de este artículo vayan a escribir una línea de useState, se detengan un instante y se pregunten: «¿a qué categoría de estado pertenece esto?».

Referencias

Durante mi trayectoria como desarrollador me he encontrado con bastante frecuencia la palabra «dominio (Domain)». Sin embargo, cuando alguien pregunta «¿qué es exactamente un dominio?», no resulta fácil dar una respuesta clara. (Sinceramente, cuando empecé a programar, pensaba que dominio se refería a www).

Al buscar información sobre el dominio, uno llega de forma natural a conceptos como modelo de dominio, objeto de dominio y modelo de objetos de dominio. Siempre he echado en falta artículos que expliquen bien en qué se diferencian y qué significan estos conceptos en el frontend, no en el backend. En este artículo partiré de la definición de cada concepto y explicaré con ejemplos cómo conviene separar y abstraer la lógica de dominio en el frontend.

Últimamente me interesa mucho el dominio fiscal. Como se acerca mayo, mes de la declaración del impuesto sobre la renta global en Corea, usaré los impuestos como ejemplo en este artículo.

Dominio (Domain)

Empecemos por la pregunta más básica. ¿Qué es un dominio?

Eric Evans lo define así en su libro Domain-Driven Design: Tackling Complexity in the Heart of Software (2003).

Una esfera de conocimiento, influencia o actividad.

"A sphere of knowledge, influence, or activity."

Dicho de forma sencilla, el dominio es la propia área problemática que se quiere resolver mediante programación. Si creamos un servicio para presentar declaraciones de impuestos, el dominio es la «declaración de impuestos»; si creamos una plataforma de reclamaciones de seguros, el dominio es la «reclamación de seguros». El dominio no es código. Es un área problemática del mundo real que existe antes que el software.

¿Qué significa esto para quien desarrolla frontend? La UI que construimos es, al fin y al cabo, una ventana (window) que permite mostrar este dominio al usuario y manipularlo. Si desarrollamos un servicio de devolución de impuestos como Toss Income o Samjjeomsam, cuyo dominio principal son los impuestos, representamos en la UI conceptos de dominio como los tipos de ingresos, el coeficiente de gastos, las deducciones sobre la renta, los créditos fiscales y el importe de la devolución. Por eso, quien desarrolla frontend también debe comprender a fondo el dominio con el que trabaja. Tan importante como crear buenos componentes de UI es saber «qué problema resuelve este servicio».

Pero incluso dentro de un único dominio como el de los «impuestos» existen numerosos subdominios. Basta con observar el flujo de cálculo del impuesto sobre la renta global que conozco a grandes rasgos.

Cada etapa de este flujo constituye un subdominio con reglas y datos propios. Dentro del gran dominio de los «impuestos» se entrelazan subdominios como ingresos (Income), deducciones (Deduction), cuota tributaria (Tax) y declaración (Filing). Cómo dividirlos en el código es precisamente la cuestión central del modelado de dominio.

Modelo de dominio (Domain Model)

Entonces, ¿qué es un modelo de dominio? ¿En qué se diferencia el dominio del «modelo de dominio»?

Martin Fowler y Eric Evans definen el modelo de dominio de la siguiente manera.

Un modelo de objetos del dominio que incorpora tanto comportamiento como datos. — Martin Fowler

An object model of the domain that incorporates both behavior and data.

Un sistema de abstracciones que describe determinados aspectos de un dominio y que puede utilizarse para resolver problemas relacionados con ese dominio. — Eric Evans

A system of abstractions that describes selected aspects of a domain and can be used to solve problems related to that domain.

La clave está en la «abstracción selectiva». Un modelo de dominio no contiene todo lo que existe en el mundo real. Del mismo modo que un director de cine no registra cada escena de la realidad, sino que elige solo las necesarias para contar una historia, el modelo de dominio selecciona y estructura únicamente los aspectos necesarios para resolver el problema.

Hay aquí un punto importante: un modelo de dominio no tiene por qué ser código. Puede ser un diagrama dibujado en una pizarra o incluso un modelo mental (Mental Model) compartido por el equipo. En definitiva, el propio término modelo de dominio puede referirse a un concepto independiente del software.

Hay una confusión especialmente frecuente entre quienes desarrollan frontend: ver la estructura de una respuesta de API y pensar «este es el modelo de dominio». Sin embargo, eso es un modelo de datos (Data Model), no un modelo de dominio.

Podemos distinguirlos así.

El modelo de datos define «qué forma tienen los datos que se intercambian», mientras que el modelo de dominio define «qué significan esos datos para el negocio y qué reglas siguen». Si no se distingue entre ambos, los componentes pasan a depender directamente de la estructura de las respuestas de la API y cualquier cambio en el esquema del backend acaba afectando a todo el frontend.

Objeto de dominio (Domain Object)

Si el modelo de dominio es un sistema de conceptos, el objeto de dominio es la entidad concreta que implementa uno de esos conceptos en el código.

En un artículo de Jason Swett, creador de Code with Jason, se define así el objeto de dominio.

Llamaría objeto de dominio a cualquier objeto de mi modelo de objetos que también exista como concepto en mi modelo de dominio.

Any object in my object model that also exist as a concept in my domain model I would call a domain object.

Es decir, si en el modelo de dominio existe el concepto de «renta global» y en el código hay un tipo llamado Income, ese Income es un objeto de dominio. Pero no todos los objetos del código son objetos de dominio. Elementos como HttpClient, LocalStorageAdapter o useDebounce son herramientas técnicas, no conceptos de dominio.

Entity y Value Object

Evans clasifica los objetos de dominio en tres categorías: Entity, Value Object y Service. (Martin Fowler denomina esta clasificación «Evans Classification»). Un Service representa una operación de dominio que no pertenece de forma natural a un objeto concreto. Como el tema central de este artículo es cómo identificar los datos, nos centraremos en Entity y Value Object.

Una Entity es un objeto con una identidad única que persiste a lo largo del tiempo y de sus distintas representaciones. Una declaración de impuestos (TaxFiling), un contribuyente (Taxpayer) o un registro de ingresos (IncomeRecord) se identifican mediante un ID único; aunque cambien sus atributos, si conservan el mismo ID siguen siendo la misma Entity. Aunque se modifiquen las deducciones de una declaración, mientras no cambie su ID, seguirá siendo la misma declaración.

Un Value Object es un objeto cuyo significado depende únicamente de la combinación de sus atributos y se considera igual a otro si todos sus valores coinciden. El dinero (Money), un tipo impositivo (TaxRate) o un tramo impositivo (TaxBracket) son objetos cuyo propio valor constituye su significado. Un «tipo impositivo del 6 %» es el mismo «tipo impositivo del 6 %» dondequiera que se utilice.

¿Por qué es importante esta distinción en frontend? Veámoslo con el siguiente ejemplo.

interface TaxFiling {
  id: string;
  taxpayerName: string;
  taxYear: number;
  status: FilingStatus;
}
 
const isSameFiling = (a: TaxFiling, b: TaxFiling) => a.id === b.id;
 
interface Money {
  amount: number;
  currency: "KRW" | "USD";
}
 
const isSameMoney = (a: Money, b: Money) =>
  a.amount === b.amount && a.currency === b.currency;

TaxFiling es una Entity porque toma el id como criterio de identidad. (Tener un campo id no define por sí solo una Entity; lo esencial es que «ese id permite decidir si dos elementos son iguales o distintos»). Money se identifica únicamente por la combinación de amount y currency, sin id, y se considera el mismo valor cuando coinciden todos sus atributos.

Las Entity se comparan por ID y los Value Object, por atributos. Si esta distinción está clara, la lógica para decidir «si estos datos son iguales o distintos» en la gestión del estado se ordena de forma natural. Al actualizar un elemento de una lista, una Entity se busca por ID y se reemplaza, mientras que un Value Object se sustituye de forma inmutable (immutable replace).

Modelo de objetos de dominio (Domain Object Model)

Ya sabemos qué son un «modelo de dominio» y un «objeto de dominio», pero ¿qué es un modelo de objetos de dominio?

Al investigar el tema, descubrí que, sorprendentemente, no existe una definición consensuada. Buena parte de la bibliografía considera «modelo de dominio», «modelo de objetos de dominio», «modelo conceptual (conceptual model)» y «modelo de objetos de análisis (analysis object model)» como sinónimos en la práctica: distintos nombres para el modelo conceptual que se dibuja durante la fase de análisis orientado a objetos.

También hay quien los considera capas algo más separadas. Una explicación representativa de esta visión sostiene que el modelo de objetos es el punto en el que el modelo de dominio se transforma en código real.

Desde esta segunda perspectiva, el modelo de objetos es la estructura de todos los objetos de código del sistema. Incluye también herramientas técnicas como HttpClient y useDebounce. Dentro de él, el subconjunto de objetos que representan conceptos de dominio y las relaciones entre ellos constituye el modelo de objetos de dominio. Esta idea enlaza con la tradición del modelado orientado a objetos, que ha definido el «Object Model» como la estructura estática de un sistema —clases, atributos, operaciones y relaciones—.

Considero que esta perspectiva resulta más práctica para quien desarrolla frontend, porque en el código que escribimos los objetos de dominio y los objetos técnicos siempre aparecen mezclados.

En definitiva, dominio → modelo de dominio → modelo de objetos de dominio → objeto de dominio es una jerarquía que va de lo abstracto a lo concreto. El dominio es el concepto más amplio y el objeto de dominio, el más concreto. Por eso, al escribir código frontend, la cuestión que realmente debemos resolver es cómo estructurar el modelo de objetos de dominio, es decir, los tipos que representan los conceptos de dominio y las relaciones entre ellos.

¿Dónde debe estar la lógica de dominio en el frontend?

Terminadas las definiciones, pasemos a la práctica. ¿Dónde debe estar la lógica de dominio en el frontend?

Khalil Stemmler, muy interesado en el diseño de software, sostuvo al principio que «la lógica de negocio no pertenece al frontend», pero más adelante revisó su postura y afirmó que «casi todo lo que hacemos arquitectónicamente en el backend también podemos y debemos hacerlo en el frontend».

Estoy de acuerdo. Por supuesto, el frontend no debe convertirse en la única fuente de verdad (Single Source of Truth) de la lógica de negocio. Ese es el papel del backend. Pero en el frontend también existe, sin duda, lógica de dominio propia del frontend.

Pensemos en un caso en el que «hay que mostrar en tiempo real la devolución estimada en función de la información introducida por el usuario». Si esta lógica de cálculo solo existe en el backend, habría que llamar a la API cada vez que el usuario corrigiese un solo dígito del importe de sus ingresos. La UI se detendría durante todo el viaje de ida y vuelta por la red y, si el usuario escribe rápido, se dispararía una cantidad enorme de peticiones innecesarias. Incluso con debounce, un retraso de varios cientos de milisegundos basta para romper la experiencia de una «vista previa en tiempo real». En última instancia, el frontend no tiene más remedio que realizar directamente los cálculos que requieren una respuesta inmediata, por lo que existe lógica que solo puede ejecutarse en el frontend.

Cuando la lógica de dominio se mezcla con el componente

Tomemos como ejemplo una pantalla de vista previa del impuesto sobre la renta global. Cuando el usuario introduce la información sobre sus ingresos, se muestra en tiempo real la cuota estimada. Este es un ejemplo habitual de código en el que se mezclan la lógica de dominio y la lógica de UI.

function TaxPreviewPage() {
  const [총수입, set총수입] = useState(0);
  const [경비율, set경비율] = useState(0.641); 
  const [인적공제대상인원, set인적공제대상인원] = useState(1); 
 
  const 종합소득금액 = 총수입 - 총수입 * 경비율;
 
  const 소득공제합계 = 인적공제대상인원 * 1_500_000;
  const 과세표준 = Math.max(0, 종합소득금액 - 소득공제합계);
 
  let calculatedTax = 0;
  if (과세표준 <= 14_000_000) {
    calculatedTax = 과세표준 * 0.06;
  } else if (과세표준 <= 50_000_000) {
    calculatedTax = 과세표준 * 0.15 - 1_260_000;
  } else if (과세표준 <= 88_000_000) {
    calculatedTax = 과세표준 * 0.24 - 5_760_000;
  } else if (과세표준 <= 150_000_000) {
    calculatedTax = 과세표준 * 0.35 - 15_440_000;
  } else {
    calculatedTax = 과세표준 * 0.38 - 19_940_000;
  }
 
  const 기납부세액 = 총수입 * 0.033;
  const refundOrPayment = 기납부세액 - calculatedTax;
 
  return <div>...</div>;
}

¿Se aprecia el problema? Las reglas de negocio fijadas por la legislación fiscal —«deducción personal de 1,5 millones de wones por persona», «ocho tramos impositivos progresivos» y «retención del 3,3 %»— están incrustadas directamente en un componente de React. La legislación fiscal cambia cada año; si estas reglas están dispersas por los componentes, cada reforma obliga a buscar todos los lugares que hay que modificar. Si además existen escenarios E2E gestionados por el equipo de QA, el coste de las pruebas tampoco será menor.

Al final, resulta difícil distinguir la lógica de vista de la lógica de negocio, y el código acaba enredado entre innumerables condicionales y hooks personalizados.

Separemos la lógica de dominio

Tomemos prestado un principio central del enfoque de Clean Architecture de Alex Bespoyasov: separar la lógica de dominio en funciones puras que no dependan de ningún framework.

El dominio es el núcleo que distingue una aplicación de otra. Puede entenderse como aquello que no cambiaría si migrásemos de React a Angular.

The domain is the core that distinguishes one application from another. You can think of the domain as something that won't change if we move from React to Angular.

Refactoricemos el ejemplo anterior del cálculo de impuestos.

Primero definimos los tipos y las reglas del dominio para cohesionar la información relacionada.

export interface Income {
  grossAmount: number;
  expenseRate: number;
}
 
export interface Deductions {
  personalCount: number;
  pensionPaid: number;
  additionalDeductions: number;
}
 
const PERSONAL_DEDUCTION_PER_PERSON = 1_500_000;
const WITHHOLDING_RATE = 0.033;
const TAX_BRACKETS = [
  { limit: 14_000_000, rate: 0.06, progressiveDeduction: 0 },
  /** ...구간들... **/
] as const;

A continuación, separamos la lógica de dominio en funciones puras.

Separamos en la función computeFullTax la lógica anterior para calcular los ingresos, las deducciones, la base imponible, la cuota y la devolución. A su vez, dividimos cada etapa en pequeñas funciones puras. Si inferimos el tipo del resultado con ReturnType<typeof computeFullTax>, no hace falta declarar otra interfaz.

Después, el componente se limita a «usar» la lógica de dominio.

import { computeFullTax } from "../domain/tax";
 
function TaxPreviewPage() {
  const [income, setIncome] = useState<Income>({
    grossAmount: 0,
    expenseRate: 0.641,
  });
  const [deductions, setDeductions] = useState<Deductions>({
    personalCount: 1,
    pensionPaid: 0,
    additionalDeductions: 0,
  });
 
  const result = computeFullTax(income, deductions);
 
  return (
    <div>
      <IncomeForm value={income} onChange={setIncome} />
      <DeductionForm value={deductions} onChange={setDeductions} />
      <TaxResultSummary result={result} />
    </div>
  );
}

¿Qué ha cambiado?

• La tabla de ocho tramos impositivos progresivos (TAX_BRACKETS) está reunida en un único lugar, por lo que, cuando cambie la legislación fiscal, solo habrá que modificar domain/tax.ts.
• El flujo de cálculo está cohesionado en una sola función, computeFullTax, lo que permite ver de un vistazo el proceso completo. (Se ha agrupado para simplificar el ejemplo, pero en un proyecto real conviene dividirlo más según su propósito: cálculo de ingresos, cálculo de deducciones, cálculo de la cuota, etc.).
• El componente se concentra únicamente en «cómo mostrarlo». Aunque cambien los tipos impositivos, no hace falta modificar el componente.
• Aunque se migre de React a otro framework, domain/tax.ts no cambia.

Cuando se separa la lógica de dominio, las pruebas se vuelven sorprendentemente sencillas. Esto es especialmente importante en el dominio fiscal, donde la precisión de los cálculos es, literalmente, el dinero del usuario.

Las funciones puras que contienen cálculos fiscales no necesitan React Testing Library, ni render, ni screen.getByText. Basta con proporcionar una entrada y comprobar la salida. Casos como «tipo del 6 % hasta 14 millones de wones», «si la base imponible es 0 wones, la cuota también es 0» o «devolución para un autónomo con 30 millones de wones de ingresos» pueden expresarse con un it de una sola línea. Las pruebas unitarias del dominio establecen de forma natural el criterio para separar componentes y, además, el código de prueba actúa como documentación.

Modelo de dominio anémico (Anemic Domain Model)

En el apartado anterior separamos la lógica de cálculo. Sin embargo, la lógica de dominio también incluye reglas de transición de estado y comprobaciones de permisos. Preguntas como «¿se puede editar ahora esta declaración?», «¿se puede presentar?» o «¿se puede cambiar el tipo de reclamación?» pertenecen a esta categoría. Al separar estas reglas es fácil caer en una trampa que Martin Fowler denominó modelo de dominio anémico (Anemic Domain Model).

Un modelo de dominio anémico es aquel en el que los tipos están bien definidos en el lenguaje del dominio, pero las reglas que operan sobre ellos se han dispersado fuera del dominio. Veamos como ejemplo el dominio de una declaración de impuestos (Filing). El tipo está limpio.

// types/filing.ts
export interface TaxFiling {
  id: string;
  status: "draft" | "submitted" | "reviewing" | "completed" | "amended";
  taxYear: number;
  filingType: "regular" | "late" | "amendment";
  determinedTax: number;
}

Pero las reglas para decidir y realizar transiciones sobre este tipo están incrustadas en otros lugares.

// utils/filingHelpers.ts
export function canAmendFiling(filing: TaxFiling) {
  return filing.status === "completed" && filing.filingType !== "amendment";
}
 
// components/FilingDetail.tsx
function FilingDetail({ filing }: { filing: TaxFiling }) {
  // 같은 도메인 규칙을 컴포넌트 안에 다시 작성한다
  const canEdit = filing.status === "draft" || filing.status === "reviewing";
  // ...
}
 
// hooks/useSubmitFiling.ts
export function handleSubmitFiling(filing: TaxFiling) {
  if (filing.status !== "draft") return;
  // ...
}

La misma regla de dominio existe con formas distintas en tres lugares: utils, un componente y un hook. Si en este estado llega un requisito como «cambian las condiciones para presentar una reclamación», habrá que recorrer el código en busca de todos los lugares que deben modificarse, y cualquier omisión provocará una decisión incorrecta en alguna parte del sitio. Fowler criticó este tipo de código por ser «poco más que código procedimental revestido con una apariencia orientada a objetos».

La solución es la misma que aplicamos a la lógica de cálculo en el apartado anterior: poner las reglas junto al tipo.

export interface TaxFiling {
  id: string;
  status: FilingStatus;
  taxYear: number;
  filingType: FilingType;
  determinedTax: number;
}
 
export type FilingStatus =
  | "draft"
  | "submitted"
  | "reviewing"
  | "completed"
  | "amended";
 
export type FilingType = "regular" | "late" | "amendment";
 
// 도메인 규칙은 도메인 옆에 둔다
export function canEdit(filing: TaxFiling): boolean {
  return filing.status === "draft";
}
 
export function canSubmit(filing: TaxFiling): boolean {
  return filing.status === "draft" && filing.determinedTax >= 0;
}
 
export function canAmend(filing: TaxFiling): boolean {
  return filing.status === "completed" && filing.filingType !== "amendment";
}

Ahora las reglas relacionadas con las declaraciones se gestionan en un único lugar, domain/filing.ts. Cualquier componente puede llamar a canAmend(filing) y, si cambia una regla, basta con modificar este archivo. La clave es entender el tipo y las reglas que operan sobre él como una sola unidad. Dejar solo el tipo en la carpeta del dominio y extraer las reglas a utils es una separación parcial que puede parecer limpia, pero sigue siendo anémica.

Capa de transformación entre la respuesta de la API y el modelo de dominio

En un proyecto real hay que tener en cuenta otra cuestión: la estructura de las respuestas de la API del backend no siempre coincide con el modelo de dominio del frontend. Esto es aún más cierto en un servicio fiscal conectado con organismos públicos. Los datos de integración con Hometax, el portal de la Agencia Tributaria Nacional de Corea, están llenos de abreviaturas y códigos, por lo que es poco probable que lleguen con la misma forma que el modelo de dominio del frontend.

Para eso necesitamos una capa de transformación (Mapper). En lugar de llevar el tipo de la respuesta de la API directamente hasta el componente, primero lo depuramos y lo convertimos en un tipo de dominio. Basta con una función pura.

import type { Income } from "../domain/tax";
 
interface HometaxIncomeResponse {
  총수입금액: number;
  경비율: number;
  소득유형코드: string;
  // ... 나머지 약어 필드들
}
 
export function toIncome(response: HometaxIncomeResponse): Income {
  return {
    총수입_금액: response.총수입금액,
    경비_비율: response.경비율,
  };
}

De este modo, las abreviaturas y clasificaciones basadas en códigos de la respuesta de la API, como 총수입금액 y 경비율, se transforman en un único lugar para adaptarlas al dominio del frontend. Los valores que deben desplegarse como enum, como el código del tipo de ingreso, pueden resolverse con una pequeña lookup table dentro del mapper. Aunque cambien los nombres de los campos de la API de Hometax, solo habrá que modificar el mapper.

Funciones utilitarias y lógica de dominio

Al separar la lógica de dominio surge inevitablemente una pregunta: «¿esto no es una función utilitaria?»

Veamos, por ejemplo, estas dos funciones.

function formatCurrency(amount: number): string {
  return `${amount.toLocaleString()}원`;
}
 
function calculateTax(taxableBase: number): number {
  const bracket = TAX_BRACKETS.find((bracket) => taxableBase <= bracket.limit);
  return Math.floor(taxableBase * bracket.rate - bracket.progressiveDeduction);
}

formatCurrency es pura lógica de presentación (Presentation) que transforma un número en texto. Añadir la unidad «won» y los separadores de miles no es una regla de negocio, sino una decisión sobre cómo mostrar el valor al usuario. En cambio, calculateTax contiene una regla de negocio basada en la legislación fiscal: «aplicar ocho tramos impositivos progresivos». Es una regla del dominio que debe aplicarse de la misma forma incluso sin UI.

Este es el criterio que uso en la práctica.

Si esta lógica desaparece, ¿se rompe el negocio o solo se rompe la pantalla?

Si se rompe el negocio, es lógica de dominio; si solo se rompe la pantalla, es lógica de presentación. Esta pregunta permite trazar la mayoría de los límites.

Pero la realidad no es tan limpia. El caso más difícil es el de la lógica que parece de dominio, pero en realidad es de presentación.

Veamos el siguiente código. Como recibe un concepto de dominio llamado FilingStatus, se ha clasificado como lógica de dominio. Pero ¿lo es realmente?

// domain/filing.ts
function getStatusBadgeColor(status: FilingStatus): string {
  const colors: Record<FilingStatus, string> = {
    draft: "gray",
    submitted: "blue",
    reviewing: "yellow",
    completed: "green",
    amended: "purple",
  };
  return colors[status];
}
 
function getStatusDisplayText(status: FilingStatus): string {
  const labels: Record<FilingStatus, string> = {
    draft: "작성 중",
    submitted: "제출 완료",
    reviewing: "검토 중",
    completed: "신고 완료",
    amended: "경정청구",
  };
  return labels[status];
}

Aunque getStatusBadgeColor y getStatusDisplayText usan el concepto de dominio FilingStatus, su función es la presentación en pantalla. Si cambia el color de la insignia, el negocio no se rompe en absoluto. Si ponemos estas funciones en domain/filing.ts, el módulo de dominio crecerá cada vez más y la auténtica lógica de dominio acabará mezclada con la lógica de presentación.

Separar el modelo de dominio y el ViewModel

Hay una forma práctica de resolver este problema: separar el ViewModel en un archivo distinto dentro de la misma carpeta del dominio. En lugar de .ui.ts, usar el nombre .viewModel.ts enlaza de forma natural con el concepto de ViewModel del patrón MVVM. El propio nombre deja claro su papel como «capa que transforma los datos de dominio para adaptarlos a la pantalla».

domains/
└── filing/
    ├── filing.ts              # 순수 도메인 모델 + 도메인 로직
    ├── filing.viewModel.ts    # ViewModel (표현 변환 계층)
    ├── filing.test.ts         # 도메인 로직 테스트
    └── filingMapper.ts        # API ↔ 도메인 변환

Movemos tal cual getStatusBadgeColor y getStatusDisplayText a filing.viewModel.ts. También reunimos aquí transformaciones como getFilingTypeLabel(type: FilingType): string, que convierte los tipos de declaración en etiquetas coreanas. filing.ts se ocupa solo de las reglas de negocio y filing.viewModel.ts, solo de su presentación en pantalla.

La clave es la dirección de las dependencias. filing.viewModel.ts importa filing.ts, pero filing.ts nunca importa filing.viewModel.ts. El dominio no conoce la presentación; la presentación sí conoce el dominio. Puede verse como una versión reducida de la regla de dependencias (Dependency Rule) de Robert C. Martin.

He colocado en la misma carpeta los archivos que cambian juntos porque considero que deben estar en el mismo directorio. Si se añade un valor nuevo al tipo FilingStatus —por ejemplo, 'rejected'—, habrá que modificar tanto filing.ts como filing.viewModel.ts. Al encontrarse en la misma carpeta, el alcance del cambio resulta evidente.

Límites y cohesión

Tan importante como separar la lógica de dominio es decidir dónde trazar los límites. Estos son algunos de los problemas al definir límites que encuentro con frecuencia en proyectos reales.

Los datos que maneja un frontend proceden, a grandes rasgos, de cuatro fuentes.

• Datos del servidor: recibidos como respuesta de una API.
• Datos derivados: calculados a partir de los datos del servidor.
• Estado de la UI: destinado a controlar la pantalla y las interacciones del usuario.
• Entrada del usuario: datos que se están introduciendo en un formulario.

Si mezclamos los cuatro en un único tipo, contaminamos el modelo de dominio.

// 안티패턴: 모든 것이 섞인 타입
interface TaxFiling {
  // 서버 데이터 (도메인)
  id: string;
  status: FilingStatus;
  determinedTax: number;
 
  // 파생 데이터 (도메인)
  refundAmount: number;
  canAmend: boolean;
 
  // UI 상태 (표현)
  isExpanded: boolean;
  activeStep: number;
 
  // 임시 상태
  editingDeductions: Deduction[];
}

Este tipo mete en el mismo recipiente conceptos de dominio, estado de la UI y datos temporales. Cada vez que cambia activeStep, es como si se actualizase el dominio de la declaración. (Cambiar de paso en un formulario no es un evento de negocio).

La mejora consiste en separar los tipos según sus límites. El modelo de dominio solo contiene conceptos de negocio como id, status y determinedTax; el estado de la UI (FilingFormViewState) contiene únicamente controles de pantalla como isExpanded y activeStep; y el estado del formulario (DeductionEditForm), solo los datos temporales que se están introduciendo.

Así, cada tipo tiene un único motivo para cambiar. Los tipos de dominio solo se modifican cuando cambia la legislación fiscal; el estado de la UI, cuando cambia el diseño de la pantalla; y el estado del formulario, cuando cambia la UX de entrada.

Mantengamos juntas las cosas que cambian juntas

En el DDD de Eric Evans existe el concepto de Aggregate (agregado): «tratar un grupo de objetos relacionados como una sola unidad». No hace falta aplicarlo literalmente en el frontend, pero sí merece la pena adoptar su principio central: mantener juntos los datos y las reglas que cambian juntos.

En un servicio fiscal, por ejemplo, Income (ingresos) y ExpenseRate (coeficiente de gastos) siempre cambian juntos. Si cambia el tipo de ingreso, también cambia el coeficiente aplicable y se ve afectado el cálculo de la renta global. Por tanto, conviene cohesionarlos en un solo archivo, domain/tax.ts.

En cambio, TaxFiling (declaración) puede cambiar con independencia del cálculo de la cuota. Aunque cambien las reglas de transición de estado de una declaración, la lógica para calcular los tipos impositivos no se ve afectada. Por tanto, es correcto separarla en domain/filing.ts.

이렇게 묻자: "A가 변할 때 B도 반드시 변해야 하는가?"
  → Yes: 같은 모듈에 둔다 (Income + ExpenseRate + TaxBracket)
  → No: 분리한다 (Tax 계산 ↔ Filing 상태관리)

Class frente a estilo funcional

Llegados a este punto puede surgir una pregunta fundamental. Todos los ejemplos anteriores combinan interface y funciones puras; ¿no sería más natural expresar el dominio con Class para lograr una mayor cohesión?

Es cierto. Cuando se expresa un dominio mediante Class, los datos y el comportamiento quedan agrupados en un mismo objeto, por lo que la cohesión se hace visible directamente en la estructura del código.

class TaxFilingModel {
  constructor(
    public readonly id: string,
    public readonly status: FilingStatus,
    public readonly taxYear: number,
    public readonly filingType: FilingType,
    public readonly determinedTax: number,
  ) {}
 
  canEdit(): boolean {
    return this.status === "draft";
  }
 
  canAmend(): boolean {
    return this.status === "completed" && this.filingType !== "amendment";
  }
 
  canSubmit(): boolean {
    return this.status === "draft" && this.determinedTax >= 0;
  }
}
 
const filing = new TaxFilingModel(
  "F-001",
  "completed",
  2025,
  "regular",
  547200,
);
 
filing.canAmend();

Con Class, el comportamiento pertenece a los datos y el sujeto queda claro allí donde se utiliza. filing.canAmend() resulta intuitivo, como una frase en lenguaje natural. El sujeto (filing) y el verbo (canAmend) están unidos de forma explícita. Del mismo modo, al escribir jihoon.eat('감자탕') se lee de inmediato que «Jihoon come gamjatang».

En el estilo funcional, en cambio, queda así.

canAmend(filing);
eat("jihoon", "감자탕");

En el enfoque funcional, los datos existen fuera de la función. Las dos líneas anteriores reciben filing como argumento y ejecutan alguna operación. La función eat recibe jihoon y 감자탕 como datos y realiza la acción.

Como resultado, la relación entre sujeto y verbo es más débil. Para saber que la función canAmend está relacionada con TaxFiling, hay que abrir el archivo o consultar su firma de tipos. Si en un mismo archivo se mezclan funciones como canAmend(filing), canEdit(filing) y calculateTax(taxableBase), puede resultar difícil saber de un vistazo a qué dominio pertenece cada una.

Entonces, ¿deberíamos usar Class?

Sinceramente, la respuesta es «depende de la situación». Sin embargo, según mi experiencia, hay razones prácticas por las que Class no es una solución universal en un entorno React + TypeScript.

1. Fricción con la gestión del estado de React

La gestión del estado de React encaja de forma más natural con Plain Object. Aunque useState y useReducer pueden contener técnicamente cualquier valor, y Redux DevTools no elimina por sí mismo el prototipo de una instancia de Class, cuando el middleware de persistencia de Redux/Zustand guarda y restaura el estado como JSON, una instancia de Class pierde sus métodos y su prototipo en el ciclo JSON.stringify → JSON.parse y queda reducida a un plain object. El límite de props entre React Server Component y Client Component impone una restricción distinta: solo admite valores serializables (serializable) compatibles, por lo que una instancia arbitraria de Class no puede atravesarlo.

Veamos el siguiente código.

const [filing, setFiling] = useState(
  new TaxFilingModel("F-001", "draft", 2025, "regular", 0),
);

Actualizar el estado de React no hace que filing deje de ser una instancia de TaxFilingModel. Sin embargo, si la persistencia de Redux/Zustand lo guarda y restaura como JSON, el valor recuperado puede ser un plain object sin métodos, y una llamada desprevenida a filing.canAmend() puede provocar un error en tiempo de ejecución. Al pasarlo de React Server Component a Client Component, el fallo ocurre antes, porque una instancia de Class no es un valor de props serializable compatible.

2. Dificultad para garantizar la inmutabilidad

React detecta los cambios de estado mediante comparación de referencias (referential equality). Si un método de una instancia de Class modifica internamente el estado con algo como this.items.push(...), la referencia no cambia y React no activa un nuevo renderizado. Así que addDeduction(item) tendría que devolver siempre una instancia nueva, por ejemplo con return new DeductionList([...this.items, item]); pero entonces se diluye la ventaja de Class de «modificar un estado encapsulado». El resultado no es muy distinto de una actualización funcional.

Estrategias para lograr cohesión con el estilo funcional

Entonces, ¿cómo podemos mejorar en el estilo funcional el problema de cohesión débil que vemos en eat('jihoon', '감자탕')? Estas son tres estrategias que me han resultado eficaces.

1. Cohesionar mediante un namespace de módulo

Es la opción más intuitiva. Se convierte el propio archivo —el módulo— en una unidad de dominio y se usa un namespace al importarlo. Podemos reutilizar tal cual el archivo domain/filing.ts definido antes.

import * as FilingModel from "../domain/filing";
 
FilingModel.canEdit(filing);
FilingModel.canAmend(filing);
FilingModel.canSubmit(filing);

Aunque FilingModel.canAmend(filing) no llega a ser tan directo como filing.canAmend(), el código deja claro al menos que la función pertenece al dominio Filing. También desaparece el riesgo de mezclar funciones de varios dominios.

2. Usar siempre como primer argumento el sujeto del dominio

Existe otra convención para expresar cohesión en el estilo funcional: colocar siempre como primer argumento al «sujeto de la acción». Si unificamos las firmas como canAmend(filing) y calculateTotalIncome(income), canAmend(filing) se lee como «consultar canAmend sobre filing». Es coherente con la forma de pensar de las pipelines de Unix (data |> transform). De hecho, el receptor de métodos de Go sigue exactamente este patrón, al igual que el bloque impl de Rust cuando recibe self como primer argumento.

3. Agrupar el comportamiento con una función de creación de objetos de dominio (Factory)

Este patrón resulta útil cuando echamos de menos la cohesión de Class. Una función factory devuelve a la vez el objeto de dominio y su comportamiento.

export function createFilingModel(data: TaxFiling) {
  return {
    ...data,
    canEdit: () => data.status === "draft",
    canSubmit: () => data.status === "draft" && data.determinedTax >= 0,
    canAmend: () =>
      data.status === "completed" && data.filingType !== "amendment",
  } as const;
}
 
const filing = createFilingModel(rawFiling);
filing.canAmend();
filing.canEdit();

Este patrón combina la expresividad de Class (filing.canAmend()) con la practicidad de componer comportamiento mediante un objeto literal. Como el objeto devuelto contiene propiedades que son funciones, no es en sí mismo un dato serializable como JSON. También tiene el coste de crear cada vez nuevos objetos de función, pero rara vez supone un problema de rendimiento con el volumen de datos habitual en frontend.

¿Hasta dónde debemos separar?

Al leer sobre Clean Architecture encontramos estructuras ideales con tres o cuatro capas y definiciones de Port/Adapter. Sin embargo, aplicar esta estructura a todos los proyectos puede convertirse en sobreingeniería (over-engineering).

Estos son, en mi opinión, unos criterios prácticos.

• Separar los tipos de dominio de los tipos de respuesta de la API. Ya sea con interface o con type, se definen en un archivo aparte los conceptos de dominio que usa el frontend.
• Extraer de los componentes la lógica que contenga reglas de negocio. No es imprescindible que esté en una carpeta domain/. Lo importante es convertirla en funciones puras que no dependan de React.
• Transformar la respuesta de la API en el modelo de dominio en un único lugar. Ya sea mediante una función Mapper o un esquema de Zod, se crea una estructura en la que basta modificar ese punto para evitar que el cambio se propague.

Si el proyecto gana complejidad, también pueden plantearse estas opciones.

• Dividir las carpetas por Bounded Context. El capítulo de frontend de Toss también recalca el principio de «colocar en el mismo directorio los archivos que cambian juntos». Al dividir las carpetas por dominios, las rutas de importación revelan de forma natural sus límites.
• Introducir una capa de Use Case. Cuando la combinación de lógica de dominio se vuelve compleja, hace falta una capa Application que reúna en una sola función un escenario como «consultar información de ingresos → aplicar el coeficiente de gastos → calcular las deducciones → calcular la cuota → determinar la devolución».

src/
├── domains/
│   ├── tax/
│   │   ├── tax.ts                  # 세액 계산 도메인 (세율, 공제, 계산 파이프라인)
│   │   ├── tax.viewModel.ts        # 세액 표현 (금액 포맷, 구간 라벨)
│   │   ├── tax.test.ts             # 세액 계산 테스트
│   │   └── incomeMapper.ts         # 홈택스 API ↔ 도메인 변환
│   ├── filing/
│   │   ├── filing.ts               # 신고 상태 도메인 (상태 전이, 권한)
│   │   ├── filing.viewModel.ts     # 신고 표현 (상태 배지, 라벨)
│   │   ├── filing.test.ts
│   │   └── filingMapper.ts
│   └── deduction/
│       ├── deduction.ts            # 공제 항목 도메인 (자격 조건, 한도)
│       └── deduction.viewModel.ts
├── hooks/                           # React 의존 로직
├── components/                      # UI 컴포넌트
└── api/                             # API 호출

Incluso dentro de un único dominio fiscal, el cálculo de la cuota (tax), la gestión de declaraciones (filing) y las deducciones (deduction) se dividen en subdominios independientes. Aunque cambien los tipos impositivos, no se ven afectadas las reglas de transición de estado de las declaraciones; aunque se añadan deducciones, el flujo para presentar una declaración permanece intacto. Esta es una aplicación práctica de Bounded Context.

Conclusión

En resumen, el dominio es el área problemática que queremos resolver; el modelo de dominio es el sistema conceptual que abstrae de forma selectiva ese problema; el modelo de objetos de dominio es la implementación en código de ese sistema conceptual; y el objeto de dominio es cada objeto individual de esa implementación.

Llevar estos conceptos a la práctica en frontend no consiste simplemente en dividir carpetas, sino en evaluar conscientemente varias capas de límites. «¿Esto es una regla de negocio o lógica de presentación?», «¿estos datos son estado de dominio o estado de la UI?», «¿esta función tiene suficiente cohesión?». El mero hábito de formularse estas preguntas mejora de forma natural la estructura del código.

Por supuesto, no todos los proyectos necesitan todas las capas de Clean Architecture. Dividir una aplicación CRUD sencilla en cuatro capas y aplicar el patrón Factory a todos los dominios sería matar moscas a cañonazos. Entre la elegante cohesión de Class y la flexibilidad práctica del estilo funcional, la respuesta depende de la complejidad del proyecto y del contexto del equipo.

No hay una única respuesta correcta. Pero existe una diferencia clara entre «escribir código sin saber qué es el dominio» y «reconocer el dominio, evaluar sus límites y separarlo conscientemente». Espero que quienes lean este artículo se pregunten al menos una vez en sus propios proyectos: «¿cuál es aquí el dominio y dónde debería estar este código?».

Referencias

Como siempre me han interesado las revisiones de código y la refactorización, decidí afrontar este interesante ejercicio publicado por Toss bajo el formato de simulacro de Frontend Fundamentals. El ejercicio consistía en refactorizar una aplicación de reserva de salas de reuniones. También incluía tests, por lo que contaba con una red de seguridad para comprobar que ninguna funcionalidad se rompiera durante el proceso.

Al final, dediqué dos días a la refactorización y quiero resumir lo que aprendí durante el proceso.

El primer encuentro con el código

Lo primero que hice al abrir el código fue leer las especificaciones de los tests. Los tests son la documentación que explica con mayor honestidad qué debe hacer una aplicación. Revisé App.easy.spec.tsx y App.hard.spec.tsx para comprender todos sus requisitos.

Después examiné el código real y encontré dos componentes monolíticos.

• ReservationStatusPage era un componente de unas 400 líneas que reunía en un único archivo la selección de fecha, la visualización de la línea temporal, el tooltip con los detalles de la reserva, la lista de mis reservas y la función de cancelación.
• RoomBookingPage era un componente de unas 300 líneas en el que se entrelazaban los filtros, la lista de salas, la lógica de creación de reservas y la sincronización de los parámetros de la URL.

Mientras leía el código, antes de decidir que «había que mejorarlo», me centré en clasificar sus características: qué partes contenían información de dominio, cuáles tenían carácter de utilidad y cuáles pertenecían exclusivamente a la capa de UI.

// 도메인 정보: 장비 라벨, 타임 슬롯 등 비즈니스 상수
const EQUIPMENT_LABELS: Record<string, string> = {
  tv: 'TV', whiteboard: '화이트보드', video: '화상장비', speaker: '스피커',
};
 
// 유틸리티: 날짜 포맷, 시간 변환
function formatDate(date: Date): string { ... }
function timeToMinutes(time: string): number { ... }
 
// 서버 상태: 인라인 useQuery, useMutation 호출
const { data: rooms = [] } = useQuery(['rooms'], getRooms);
const { data: reservations = [] } = useQuery(['reservations', date], () => getReservations(date));
 
// UI + 비즈니스 로직 혼재: 필터링, 정렬, 충돌 감지가 JSX 사이에 산재

Esta clasificación hizo que empezara a resultar evidente por dónde debía comenzar. Añadí comentarios breves en cada área del código para anotar posibles mejoras. (Me recordó a cuando entré en mi empresa actual y tuve que migrar un proyecto basado en jquery).

Entonces, ¿por dónde debía empezar?

Definir la estrategia de refactorización

Decidí llevar a cabo la refactorización en el siguiente orden.

1. Gestión del código de servidor: separar queries y mutations
2. Separación de la lógica de dominio: modelos Equipment, Room y Reservation
3. Declaración de tipos: organizar el sistema de tipos a partir de los modelos de dominio
4. Separación de funciones de utilidad: formato de fechas, cálculos de la línea temporal, etc.
5. Separación de la capa de UI: dividir los componentes en unidades manejables según sus responsabilidades
6. Abstracción y separación de responsabilidades: gestión de errores/carga y de query keys

Elegí este orden para avanzar desde el exterior hacia el interior siguiendo la dirección de las dependencias. Primero organizaría la infraestructura —código de servidor y utilidades—, después establecería los modelos de dominio y, por último, puliría la UI. Si separaba primero los componentes de UI, podía acabar trasladando entre varios componentes una lógica de dominio y un código de queries que todavía no estaban organizados.

Con la estrategia definida, era hora de ponerla en práctica paso a paso.

Empezar por el código de servidor y las utilidades

Separar la utilidad de formato de fecha

Lo primero que modifiqué fue la función formatDate, porque estaba definida inline por separado y de forma idéntica en ambas páginas.

// utils/formatYYYYMMDD.ts
export function formatYYYYMMDD(date: Date): string {
  const year = date.getFullYear();
  const month = String(date.getMonth() + 1).padStart(2, '0');
  const date = String(date.getDate()).padStart(2, '0');
  return `${year}-${month}-${date}`;
}

Aunque era un cambio pequeño, tenía un significado importante como primer commit de la refactorización. Era una especie de calentamiento: empezar por la parte más independiente y con menos efectos secundarios para comprobar que los tests siguieran pasando.

Separar los hooks de React Query

A continuación, extraje a archivos independientes las llamadas a useQuery y useMutation que estaban escritas directamente dentro de los componentes. Utilicé el patrón queryOptions para convertir la configuración de las queries en unidades reutilizables.

Durante este proceso también definí de forma explícita los tipos de respuesta de la API que se encontraban en remotes.ts. Los tipos que antes se propagaban como any pasaron a estar claramente definidos como GetRoomsResponse, GetReservationsResponse, etc.

Una vez organizada la capa de infraestructura, podía centrarme en los modelos de dominio.

Separar los modelos de dominio

El punto de inflexión más importante de la refactorización fue separar los modelos de dominio en un directorio models/ independiente.

En el código original, constantes de negocio como EQUIPMENT_LABELS y TIME_SLOTS estaban declaradas al principio de los archivos de componentes. Los tipos de Room y Reservation solo existían en el handler del servidor (_tosslib/server/types.ts) y, en el código del cliente, se utilizaban prácticamente como any.

// models/equipment.ts
export const EQUIPMENT_LABELS = {
  tv: 'TV', whiteboard: '화이트보드', video: '화상장비', speaker: '스피커',
} as const;
 
export type Equipment = keyof typeof EQUIPMENT_LABELS;
export const ALL_EQUIPMENT = Object.keys(EQUIPMENT_LABELS) as Equipment[];

// models/reservation.ts
export interface Room {
  id: string;
  name: string;
  floor: number;
  capacity: number;
  equipment: Equipment[];
}
 
export interface Reservation {
  id: string;
  roomId: string;
  date: string;
  start: string;
  end: string;
  attendees: number;
  equipment: Equipment[];
}

¿Por qué es importante separar los modelos de dominio? Cuando la lógica de negocio depende de un componente de UI, para modificarla también hay que revisar la lógica de renderizado del componente. En cambio, si reside de forma independiente en el directorio models/, las reglas de negocio pueden modificarse por separado de la UI. Por supuesto, una separación perfecta es difícil de lograr en la práctica, pero lo esencial es crear, como mínimo, una estructura que permita predecir que «esta lógica estará aquí».

Una vez separados los modelos de dominio, ¿hasta qué punto podía aligerarse la UI?

Descomponer los componentes

ReservationStatusPage

Este fue el commit que produjo el cambio más drástico y también el que más tiempo me llevó. Dividí el componente monolítico de 385 líneas de la siguiente manera.

ReservationStatusPage/
├── index.tsx                    # 페이지 레벨
└── components/
    ├── DateSelector.tsx         # 날짜 선택 UI
    ├── ReservationTimeline.tsx  # 타임라인
    └── MyReservation.tsx        # 내 예약 목록 + 취소

El criterio para separar cada parte fue «¿tiene este código sentido de manera independiente?». Visualizar la línea temporal es una responsabilidad independiente que recibe los datos de las reservas de una fecha y dibuja una cuadrícula. Consultar y cancelar las reservas del usuario también lo es. No había ningún motivo para que estuvieran en el mismo archivo.

Después de la separación, index.tsx quedó limitado al papel de orquestador (orchestrator). Se encargaba de gestionar el estado, mostrar mensajes y componer los subcomponentes, mientras que delegaba en ellos el fetching de datos y los detalles de renderizado.

RoomBookingPage

Dividí la página de reservas siguiendo el mismo principio.

RoomBookingPage/
├── index.tsx                    # 페이지 레벨
├── components/
│   ├── BookingFilter.tsx        # 날짜, 시간, 인원, 장비, 층 UI
│   └── AvailableRoomList.tsx    # 예약 가능 방 목록
└── hooks/
    └── useBookingParams.ts      # URL searchParams 기반 상태 관리

Durante el proceso tomé una decisión interesante. Al principio intenté introducir react-hook-form + zod para validar el formulario. Sin embargo, finalmente los eliminé y los sustituí por el hook personalizado useBookingParams. Más adelante explicaré esta decisión con mayor detalle.

Llegados a este punto, surge una pregunta de forma natural: ¿hasta dónde debemos abstraer?

El nivel adecuado de abstracción

Esta fue la parte sobre la que más reflexioné durante el simulacro.

¿Hasta qué punto conviene descomponer las condiciones anidadas?

La lógica que determina si una sala se puede reservar combina varias condiciones: si la capacidad es suficiente, si cuenta con el equipamiento necesario, si está en la planta preferida y si existe un solapamiento horario. En el código original, todas ellas estaban escritas inline dentro de un único callback de filter.

Al extraer esta lógica a models/roomFilter.ts, separé cada condición en una función con nombre.

const isEnoughCapacity = (room: Room, attendees: number) => room.capacity >= attendees;
const hasRequiredEquipment = (room: Room, equipment: Equipment[]) =>
  equipment.every(eq => room.equipment.includes(eq));
const isOnPreferredFloor = (room: Room, floor: number | null) =>
  floor === null || room.floor === floor;
const hasNoTimeConflict = (room: Room, reservations: Reservation[], date: string, start: string, end: string) =>
  !reservations.some(reservation => reservation.roomId === room.id && reservation.date === date && reservation.start < end && reservation.end > start);
 
export function filterAvailableRooms(rooms: Room[], reservations: Reservation[], params: Params): Room[] {
  return rooms
    .filter(room =>
      isEnoughCapacity(room, params.attendees) &&
      hasRequiredEquipment(room, params.equipment) &&
      isOnPreferredFloor(room, params.floor) &&
      hasNoTimeConflict(room, reservations, params.date, params.startTime, params.endTime)
    )
    .sort((a, b) => {
      if (a.floor !== b.floor) return a.floor - b.floor;
      return a.name.localeCompare(b.name);
    });
}

La clave está en que solo separé en funciones aquello que podía recibir un nombre claro. Nombres como isEnoughCapacity y hasRequiredEquipment permiten predecir qué hace cada función sin mirar su implementación. Si el nombre tuviera que ser ambiguo, como processRoomConditions, la abstracción podría aumentar la carga cognitiva de quien lee el código.

Esto no significa, por supuesto, que sea la única respuesta correcta. Mi criterio fue «¿se puede predecir el comportamiento con solo leer el nombre de la función?». Si es así, merece la pena abstraer; si no, dejarlo inline puede favorecer la legibilidad.

searchParams frente al estado del formulario

También reflexioné bastante sobre dónde debía residir el estado de los filtros de reserva. En el código original, cada valor se gestionaba mediante useState y se sincronizaba con los searchParams de la URL mediante useEffect.

// 원본: useState + useEffect 동기화 방식
const [date, setDate] = useState(searchParams.get('date') || formatDate(new Date()));
const [startTime, setStartTime] = useState(searchParams.get('startTime') || '');
 
// ... 6개의 개별 상태
useEffect(() => {
  const params: Record<string, string> = {};
  if (date) params.date = date;
 
  // ... 모든 상태를 searchParams에 동기화
  setSearchParams(params, { replace: true });
}, [date, startTime, endTime, ...]);

Primero probé a introducir react-hook-form + zod para gestionarlos como un formulario. Sin embargo, finalmente los eliminé y los sustituí por el hook useBookingParams, que utiliza los searchParams como única fuente de verdad (Single Source of Truth).

// useBookingParams: searchParams가 곧 상태
export function useBookingParams() {
  const [searchParams, setSearchParams] = useSearchParams();
 
  const params = useMemo<BookingParams>(() => ({
    date: searchParams.get('date') || formatYYYYMMDD(new Date()),
    startTime: searchParams.get('startTime') || '',
    // ...
  }), [searchParams]);
 
  const updateParam = useCallback(<K extends keyof BookingParams>(key: K, value: BookingParams[K]) => {
    setSearchParams(prev => {
      // 기존 파라미터 병합 후 업데이트
      return result;
    }, { replace: true });
  }, [setSearchParams]);
 
  return { params, updateParam };
}

El principal motivo de esta decisión fue considerar que «no conviene que estos estados evolucionen por separado». Si tanto useState como searchParams mantienen su propio estado, pueden producirse discrepancias según el momento de la sincronización. En cambio, si solo se utilizan los searchParams como estado, la URL pasa a ser el estado de la aplicación y el problema de sincronización desaparece por completo. Además, si el usuario comparte la URL, se puede reproducir el mismo estado de los filtros.

Encontré reflexiones similares en los artículos de otros participantes: «unifiqué los searchParams de la URL como única fuente de verdad» y «opté por agrupar las props individuales de los filtros en un único objeto filter». Aunque las soluciones se expresaban de forma distinta, partían del mismo diagnóstico: «los estados dispersos deben agruparse bajo un solo concepto».

Estabilidad

Suspense y ErrorBoundary

Una vez definida la estructura de los componentes, añadí la gestión de errores y estados de carga. El orden es importante porque solo se puede decidir dónde establecer un Boundary después de definir el árbol de componentes.

Utilicé la librería react-error-boundary para envolver cada unidad independiente de fetching de datos con ErrorBoundary y Suspense. Aunque falle la línea temporal, la lista de mis reservas debe seguir mostrándose con normalidad, y viceversa.

{/* 각 영역이 독립적으로 에러/로딩을 처리 */}
<ErrorBoundary FallbackComponent={ErrorFallback} resetKeys={[date]}>
  <Suspense fallback={<Loading message="예약 현황을 불러오는 중..." />}>
    <ReservationTimeline date={date} />
  </Suspense>
</ErrorBoundary>
 
<ErrorBoundary FallbackComponent={ErrorFallback}>
  <Suspense fallback={<Loading message="내 예약을 불러오는 중..." />}>
    <MyReservation onCancel={handleCancel} />
  </Suspense>
</ErrorBoundary>

Gestión centralizada de las query keys

Al separar los hooks de las queries durante la refactorización, surgió el problema de que las query keys quedaron dispersas en varios archivos. Esto dificultaba saber qué key debía utilizarse para la invalidation dentro del onSuccess de una mutation.

Introduje @lukemorales/query-key-factory para gestionar las query keys de forma centralizada.

// queries/queryKeys.ts
export const roomKeys = createQueryKeys('rooms', {
  list: { queryKey: null, queryFn: () => remotes.getRooms() },
});
 
export const reservationKeys = createQueryKeys('reservations', {
  list: (date: string) => ({ queryKey: [date], queryFn: () => remotes.getReservations(date) }),
  my: { queryKey: null, queryFn: () => remotes.getMyReservations() },
});

Así se pueden utilizar con la forma useSuspenseQueries({ queries: [roomKeys.list, reservationKeys.list(date)] }), de modo que la query key y la función de fetching siempre se desplazan juntas. También extraje las rutas como constantes PATHS para eliminar strings hardcodeados.

¿Cuál era la intención de quienes diseñaron el ejercicio?

Después de terminar la refactorización, tomé cierta distancia y reflexioné: ¿qué pretendía evaluar este simulacro?

Al leer los artículos de otros participantes, descubrí un punto en común interesante. En casi todos aparecía la frase «el código no se lee, se predice». Nuestro cerebro no interpreta el código línea por línea, sino que lo lee anticipándose a partir de los patrones acumulados mediante la experiencia. Cuando esas predicciones fallan, la carga cognitiva aumenta drásticamente.

Desde esta perspectiva, el simulacro no evalúa simplemente la capacidad de programar, sino la capacidad de colaborar: «¿hasta qué punto puedes hacer que el código que leerán tus compañeros sea predecible?». (Tal vez la auténtica habilidad de un ingeniero de software sea leer la mente tanto de quienes diseñan el ejercicio como de sus compañeros).

Al revisar las experiencias de otros participantes, me identifiqué con ideas como «no es fácil entender el código que ha escrito otra persona» y «es importante diseñar primero la interfaz, pero ese enfoque puede tambalearse ante una gran base de código existente». Yo también viví algo parecido. Cuando el código existente ya funciona, surge la tentación de justificar su estructura: «Si ya funciona, ¿para qué cambiarlo?». Sin embargo, el objetivo central del simulacro era superar precisamente esa tentación y evaluar «con qué rapidez podría entender este código otra persona y si uno es capaz de analizar y resolver el problema con su propio criterio».

Lo que aprendí de la refactorización

El orden de la refactorización determina el resultado. Avanzar desde el exterior —la infraestructura— hacia el interior —la UI— fue la ruta más segura para evitar enredos a mitad del proceso. Al dividir los componentes después de organizar las utilidades y los modelos de dominio, las dependencias de cada componente quedaron claras.

El criterio para abstraer es el «nombre». Si al extraer algo a una función o variable su nombre puede explicar el comportamiento, merece la pena abstraerlo. Si el nombre será inevitablemente ambiguo, dejarlo inline puede ser una opción mejor.

La ubicación del estado es la arquitectura. Los estados que deben evolucionar juntos tienen que residir en el mismo lugar. Desde un punto de vista estructural, es más sano utilizar únicamente los searchParams como fuente de verdad que sincronizar useState con searchParams.

Conclusión

Después de terminar el ejercicio, conversé con dos compañeros. Al hablar y desarrollar mis ideas empezaron a surgir aspectos que no había visto mientras examinaba el código en solitario. En cuanto alguien pregunta «¿por qué lo hiciste así?» sobre una decisión estructural que yo había dado por sentada, aparecen lagunas de criterio de las que no era consciente.

Es cierto que la IA está reduciendo drásticamente el tiempo necesario para escribir y revisar código. Aun así, experiencias como esta son la razón por la que sigo considerando importantes las revisiones de código y las reuniones diarias. La IA puede comprobar la coherencia del código, pero señalar «esta es la perspectiva que has pasado por alto» sigue siendo responsabilidad de un compañero que comparte el mismo contexto. Descubrir lo que yo no había visto y estabilizar el producto gracias a ese descubrimiento: ¿no es esa la esencia de la colaboración?

No existe una única respuesta correcta al escribir código mientras resolvemos un problema. Otros participantes que hicieron el mismo simulacro eligieron caminos distintos, cada uno con sus propios motivos. Lo importante es poder explicar «por qué está escrito así». Recomiendo a quienes lean este artículo que, al menos una vez, observen su código desde la perspectiva de alguien que lo ve por primera vez. Esa mirada puede convertirse en el criterio más poderoso para determinar la calidad del código.

Uno de los textos que más me impresionó cuando era junior fue «Hoja de ruta profesional para ingenieros frontend: tres vías de especialización para perfiles junior», de Hwidong Bae. El artículo organizaba la carrera de un ingeniero frontend en tres vías: especialización web (Software Engineer) / especialización en producto (Product Engineer) / especialización en operaciones (Full-Stack Engineer), y abordaba además las «cinco competencias básicas de un ingeniero excelente» y los «tres puntos clave para convertirse en senior». En aquel entonces, la gran cuestión era decidir qué competencias desarrollar en cada vía. Sin embargo, ni siquiera habían pasado dos años desde que leí aquel texto cuando la propia cuestión cambió por completo.

Últimamente, cuando hablo con otros ingenieros, percibo que sus inquietudes tienen un tono algo distinto de las que venía oyendo durante los últimos años.

• «En la empresa hemos adoptado la IA y, si le damos un diseño, prácticamente lo construye todo. Es cómodo, pero...»
• «El mercado laboral está realmente frío».
• «Me da miedo hacer merge sin más del código generado por la IA, pero revisarlo línea por línea reduce la eficiencia. No sé qué hacer».

Yo también pasé por una etapa parecida y todavía sigo en ella. Hace apenas uno o dos años veía la IA como «una buena herramienta de apoyo»; hoy, en cambio, hemos llegado a un entorno en el que cuesta imaginar el desarrollo sin IA (yo mismo le estoy pidiendo a Claude que investigue mientras escribo este artículo). Este texto pretende ser una especie de continuación del de Hwidong Bae: quiero ordenar, desde mi punto de vista, cómo ha cambiado el panorama desde entonces y qué competencias adicionales debemos desarrollar como ingenieros frontend en este nuevo escenario.

Una vez más, he intentado buscar y contrastar tantos datos como fuera posible, pero, dado que este campo cambia a una velocidad extraordinaria, pido de antemano comprensión si alguna parte ya ha quedado anticuada cuando se publique el artículo. Si hay algo que rebatir o debatir, no dudéis en dejarlo en los comentarios.

«¿Pero ahora no lo hace todo la IA?»

Antes que nada, hay una cuestión que debemos aclarar. ¿Es cierta la frase «la IA lo hace todo»? ¿Hasta qué punto es verdad y a partir de dónde empieza la ilusión?

En febrero de 2025, Andrej Karpathy, cofundador de OpenAI y antiguo director de IA de Tesla, publicó esta frase en Twitter.

Hay un nuevo tipo de programación al que llamo «vibe coding»: consiste en dejarse llevar por completo por las vibraciones, abrazar el crecimiento exponencial y olvidar incluso que el código existe.

There's a new kind of coding I call 'vibe coding', where you fully give in to the vibes, embrace exponentials, and forget that the code even exists.

El vibe coding es, en pocas palabras, «una forma de programar en la que se le entrega el teclado a la IA y uno se limita a describir en lenguaje natural lo que quiere». No hay documentos de arquitectura, ni boilerplate, ni búsquedas de puntos y comas. El código simplemente avanza siguiendo el vibe. En menos de un año, el término se asentó como parte del vocabulario habitual de la comunidad de desarrolladores anglófona.

Sin embargo, exactamente un año después, en febrero de 2026, el mismo Karpathy dio un paso atrás. Propuso sustituir la expresión vibe coding por «agentic engineering». La diferencia entre ambos conceptos es clara.

• Vibe coding: describir lo que se quiere y aceptar el resultado.
• Agentic engineering: diseñar el sistema, especificar las restricciones y utilizar la IA para acelerar una implementación cuyo razonamiento ya se ha completado mentalmente.

Si hace un año el punto de partida era «basta con pedírselo y lo construye todo», ahora la propia «capacidad de diseñar qué pedirle a la IA y cómo hacerlo» se ha convertido en una competencia de ingeniería. Y esta corriente no se limita al tuit de una sola persona. Por esas mismas fechas, el ingeniero de Google Addy Osmani publicó el libro Beyond Vibe Coding: From Coder to AI-Era Developer, donde sentenció: «La IA no es más que un asistente, no un programador autónomo en el que se pueda confiar. Tú eres el desarrollador senior y el LLM existe para acelerar tu criterio».

Las herramientas avanzan sin freno

El ecosistema de herramientas también evoluciona rápidamente en consonancia con esta corriente. A mayo de 2026, las herramientas de programación más mencionadas son Cursor, Claude Code, GitHub Copilot, Windsurf, v0 by Vercel, Bolt.new y Devin.

La evolución de v0 es especialmente simbólica. Vercel utiliza la expresión «90% problem», que significa que el 90% del desarrollo real tiene lugar dentro de una base de código y una infraestructura ya existentes. Al principio bastaba con que v0 creara buenos prototipos greenfield; ahora importa repositorios de GitHub para trabajar directamente con ellos, aplica sistemas de diseño y obtiene automáticamente las variables de entorno de despliegue. En cierto modo, el ecosistema de herramientas está respondiendo directamente a la objeción de los perfiles senior: «¿La IA no sirve únicamente para crear demos de juguete?».

Las bases de código de las grandes tecnológicas son el mejor escaparate de este cambio.

Sundar Pichai, de Google, anunció en la presentación de resultados del tercer trimestre de octubre de 2024 que «más del 25% del código nuevo había sido generado por IA y después revisado y aprobado por ingenieros», y en abril de 2025 afirmó que la cifra había superado el 30%. Satya Nadella, de Microsoft, reveló en LlamaCon, en abril de 2025, que «hasta el 30% de nuestro código está escrito por IA». En Meta, el objetivo interno ha llegado al nivel de que «para la primera mitad de 2026, el 65% de los ingenieros genere con IA más del 75% de sus commits».

En Corea la tendencia no es distinta. Toss construyó un sistema de documentación basado en IA para mejorar la DX y evitar que los desarrolladores tuvieran que buscar documentos, y fue aún más lejos al tratar temas como «Qué ocurrió al eliminar a los diseñadores en la era de la IA». Daangn comparte experimentos de cada equipo todos los martes mediante AI Show & Tell y empezó a utilizar el eslogan de contratación «De ingeniero a builder». Woowa Brothers, por su parte, transmite mediante artículos como «En una era en la que la IA escribe código, ¿aun así queréis ser desarrolladores?» el mensaje de que «la esencia de un desarrollador no está en el código, sino en la capacidad de definir y resolver problemas».

Sin embargo, las cifras cuentan una historia algo distinta

Si nos quedáramos solo con lo anterior, sería fácil concluir que «ahora basta con pedírselo y todo se resuelve». Pero los datos reales cuentan una historia algo distinta.

Veamos primero las cifras de la 2025 Stack Overflow Developer Survey, que analiza de forma integral el estado del desarrollo de software.

• El 84% de los desarrolladores afirmó utilizar herramientas de IA o tener previsto hacerlo. (Un aumento respecto al 76% de 2024).
• El 51% de los desarrolladores profesionales usa herramientas de IA a diario.
• Sin embargo, la opinión favorable hacia las herramientas de IA (positive sentiment) disminuyó. Tras superar el 70% en 2023 y 2024, cayó hasta el 60% en 2025.
• Los desarrolladores senior con más de diez años de experiencia son quienes menos confían en los resultados de la IA.

En resumen: «Todo el mundo las usa, pero cada vez se fía menos».

Un experimento realizado en 2025 por el instituto de investigación sin ánimo de lucro METR muestra de forma aún más llamativa la brecha entre esta percepción y la realidad. Fue un experimento controlado en el que se asignó aleatoriamente el uso o no de IA a 16 desarrolladores expertos de código abierto, con una media de cinco años de experiencia y 1.500 commits, para que completaran 246 tareas. Los resultados fueron los siguientes.

• Antes de empezar, los desarrolladores predijeron que «con IA serían un 24% más rápidos».
• Justo después de terminar las tareas, seguían valorando que «parecía que habían sido alrededor de un 20% más rápidos».
• Sin embargo, la medición real mostró que habían sido un 19% más lentos.

Las causas señaladas por los investigadores son interesantes. La tasa de aceptación del código generado por la IA fue inferior al 44%; incluso el código rechazado exigió tiempo de revisión y pruebas, y hasta el código aceptado requirió bastante tiempo de revisión y corrección. Esa ilusión de haber ido más rápido pese a haber tardado más es una de las razones por las que los desarrolladores senior se muestran cada vez más escépticos ante la IA.

Además, la propia «calidad del código escrito por IA» tampoco es impecable. Veamos el experimento de Veracode, que pidió a más de cien modelos de IA que escribieran código.

• El 45% del código generado por IA contenía vulnerabilidades de seguridad del OWASP Top 10.
• La tasa de fallos en la protección contra XSS (cross-site scripting) fue del 86%.
• La tasa de fallos en la protección contra Log Injection fue del 88%.
• Otro estudio informó de que la densidad de vulnerabilidades del código de IA era 2,7 veces mayor que la del código humano.

El 86% de fallos en XSS, algo directamente relacionado con el frontend, merece especial atención. La cifra muestra muy bien qué implica hacer merge sin más de un form input creado por la IA. (A quienes tengan experiencia con auditorías de seguridad frontend ya les resulta incómodo y preocupante escribir personalmente dangerouslySetInnerHTML; parece aún más aterrador cuando la IA lo introduce a escondidas).

Las señales sobre la calidad son parecidas. GitClear analizó 211 millones de líneas de cambios de código entre 2020 y 2024 y obtuvo estos resultados.

• Porcentaje de código revertido en las dos semanas posteriores a su escritura (Code Churn): 5,5% en 2020 → 7,9% en 2024.
• Porcentaje correspondiente a refactorización: 25% en 2021 → menos del 10% en 2024.
• Porcentaje de copia y pega (clones): 8,3% en 2021 → 12,3% en 2024 (en 2025 llegó a multiplicarse por cuatro).

La interpretación no es muy difícil. Ha aumentado la capacidad de producir código rápidamente, pero ha disminuido la de escribir código que merezca la pena revisar y mejorar. Los datos de Apiiro, basados en el análisis de empresas Fortune 50, son aún más contundentes. Los desarrolladores asistidos por IA producen entre tres y cuatro veces más commits que sus compañeros, pero generan diez veces más security findings. Las rutas de escalada de privilegios (privilege escalation) aumentaron un 322% y los defectos de diseño arquitectónico, un 153%.

Qué ha sustituido la IA y qué no ha podido sustituir

Las herramientas avanzan sin freno, pero las cifras presentan matices. Entonces, ¿qué ha sustituido exactamente la IA y qué no ha podido sustituir todavía? Solo si distinguimos claramente ambas cosas podremos saber dónde debemos invertir nuestro tiempo.

Lo que se ha sustituido es parte del trabajo de teclear directamente que hacían los desarrolladores. Hay menos situaciones en las que debamos escribir boilerplate o código repetitivo; con solo un diseño se puede obtener en pocos minutos una pantalla que respete las convenciones, y tanto el tiempo de búsqueda sobre sintaxis y API como la curva de aprendizaje se han reducido drásticamente. En suma, la IA ha igualado la «velocidad de producción».

Pero todavía no ha sustituido el ámbito del «criterio». (Para ser exactos, sería más apropiado decir que «todavía no ha satisfecho las expectativas». Aunque existen diferencias entre personas en la capacidad de aprovechar la IA, aquí desarrollaré el argumento a partir de una experiencia de uso promedio).

El primer escollo es traducir los requisitos en especificaciones. Convertir necesidades de negocio ambiguas en casos límite precisos y máquinas de estados sigue requiriendo una intervención humana más profunda. Lo mismo ocurre con comprender el impacto en todo el sistema: aunque la IA ofrezca respuestas plausibles a preguntas como qué efecto tiene este componente sobre el bundle, si una dependencia permite tree shaking o cómo afecta un patrón de data fetching a la puntuación de Core Web Vitals denominada INP (Interaction to Next Paint), al final uno solo se queda tranquilo cuando una persona vuelve a revisarlas.

Tampoco pueden dejarse de lado la seguridad y la evaluación de riesgos, como demuestra el problema ya mencionado del 45% de vulnerabilidades OWASP; ni ámbitos como mantener el sistema de diseño y la coherencia, comprobando que un componente nuevo se ajuste a los tokens, las reglas de accesibilidad y los patrones de interacción existentes; o entender el contexto del cliente y del mercado, preguntándose por qué hace falta una función y en qué flujo de usuario debe integrarse.

Por último, tomando prestada una expresión del artículo de yceffort, la gestión de la deuda cognitiva (Cognitive Debt) —«la brecha entre la complejidad del sistema y el grado en que el equipo lo comprende»— es precisamente un ámbito en el que la distancia crece aún más rápido desde la adopción de la IA. Por eso, la tarea de cerrar esa brecha sigue correspondiendo a las personas.

Lo que desaparece no es el desarrollador, sino la forma que tenía su trabajo. El cuello de botella ha pasado de la «velocidad para construir» a la «velocidad para decidir».

En la misma línea, el artículo de Toss «¿Serán sustituidos los desarrolladores por la IA?» ofrece un diagnóstico de mayor calado. Su idea principal es esta: la IA no reemplaza a toda la fuerza laboral, sino que está eliminando la escalera de aprendizaje (apprenticeship ladder). Dentro de diez o veinte años, cuando los senior actuales se jubilen, faltará la siguiente generación capaz de diseñar sistemas complejos. No es una cuestión del nivel de «qué haremos con la contratación del año que viene en nuestra empresa», sino una especie de bomba de relojería para todo el sector. (Creo que es un artículo realmente bien escrito para una época llena de incertidumbre).

La «primera versión que funciona» creada por la IA representa el 70%. El 30% necesario para llegar a una «versión que pueda ofrecerse a usuarios reales» pertenece a las personas. Y la capacidad de completar ese 30% no aparece de la noche a la mañana. Esa es la esencia del problema de la escalera de aprendizaje. Si desaparece el tiempo de «ensuciarse las manos» escribiendo boilerplate y componentes sencillos, también desaparecen quienes podrían completar ese 30%.

El artículo original de Hwidong Bae enumeraba como «cinco competencias básicas de un ingeniero excelente» escribir buen código, maximizar el valor presente (equilibrar un lanzamiento rápido y la mantenibilidad a largo plazo), tomar decisiones basadas en datos, ayudar eficazmente a los compañeros a decidir y aprender de forma constante. Las cinco siguen siendo válidas en la era de la IA, pero la última ocupa la posición más vulnerable. El aprendizaje no ha desaparecido; ha cambiado su objeto. Antes aprendíamos «cómo se usa esta herramienta»; ahora debemos dedicar tiempo a aprender «cómo funciona todo este sistema». Más inquietante aún es el problema señalado por Evan Moon: «en cuanto la IA se encarga de escribir el código, la carga cognitiva del cerebro cae drásticamente». Que disminuya la carga cognitiva suena bien, pero es peligroso porque esa carga era precisamente la materia prima del aprendizaje. Cuanto más cómodo resulta, menos se crece.

Aquí surge de forma natural una pregunta. Entonces, ¿han dejado de tener sentido las tres vías del artículo de Hwidong Bae —especialización web, en producto y en operaciones—?

Yo no lo creo. Las vías siguen siendo válidas. Lo adecuado es considerar que cada una ha evolucionado un nivel para adaptarse a la era de la IA. Veamos cómo ha cambiado el panorama en cada caso.

De productor a «verificador»

En el artículo original de Hwidong Bae, la vía de especialización web se agrupaba bajo el nombre de Software Engineer. Sus pilares eran «la comprensión profunda y el uso de Internet, los navegadores web y HTML/CSS/JS», el conocimiento de las ventajas e inconvenientes de las herramientas del ecosistema web, la experiencia resolviendo problemas y una actitud receptiva a las nuevas tecnologías. Como caminos hacia un puesto senior se proponían ingeniero en una empresa que desarrolla herramientas para el ecosistema web / formador de frontend / tech lead en una organización con productos complejos. En pocas palabras, eran «personas que profundizan en el funcionamiento del navegador y de HTML/CSS/JS», y hasta hace uno o dos años su mayor arma era «poder escribir código con más precisión que nadie».

¿Cómo ha cambiado su valor en la era de la IA? Si atendemos únicamente a la velocidad para escribir código, la IA ya los ha alcanzado. Sin embargo, «la capacidad de evaluar con precisión el código escrito por la IA» se ha convertido prácticamente en patrimonio exclusivo de estos perfiles.

• Persona no desarrolladora que utiliza IA: se ha implementado según mis requisitos y funciona correctamente.
• Desarrollador que utiliza IA: funciona, pero esta dependencia puede causar ciertos problemas, y mejorar este patrón de esta forma encajaría mejor con las convenciones. Revisemos también las partes relacionadas.

En el estudio de Veracode ya mencionado aparecían tasas de fallo del 86% en XSS y del 88% en Log Injection. Quienes pueden detectar y corregir esos problemas somos precisamente los especialistas como nosotros. Estos perfiles evolucionan de manera natural hacia funciones senior de control de calidad (QA) de lo producido por la IA.

Además, al ámbito de los especialistas se ha añadido un tema completamente nuevo: la UI generativa (Generative UI) y el diseño de interfaces de IA. Algunos ejemplos son las interfaces de chat que renderizan por streaming las respuestas de un LLM, los controles de abort para detenerlas a mitad de camino, el renderizado progresivo de Markdown y bloques de código, la UX que muestra inline los resultados de las llamadas a herramientas y la integración de asistentes mediante Vercel AI SDK o MCP (Model Context Protocol). En este campo, se está disparando la demanda de «personas que conozcan con precisión cómo funciona la web y, al mismo tiempo, comprendan las características operativas de los LLM y sepan aplicarlas y aprovecharlas».

La evolución natural hacia Product Engineer

La vía de especialización en producto es la que más se ha beneficiado. Quienes comprenden bien el mercado y a los clientes y se comunican a menudo con las partes interesadas externas han obtenido, al incorporar la IA, un arma mucho más potente. Otra característica de esta vía era que, entre los caminos hacia puestos senior, también se proponía la expansión hacia otras profesiones, como ingeniero de growth o consultor / transición a PM, PO o CPO.

Un cambio interesante es que el nombre de esta vía ha empezado a convertirse en un estándar global. El artículo original ya la llamaba «Product Engineer», pero cuando lo leí la expresión me resultaba algo desconocida. Un año después, se ha asentado hasta el punto de que Vercel cambió en bloque «Fullstack Engineer» por «Product Engineer» en las descripciones de sus puestos.

Lee Robinson señala tres cualidades esenciales de un Product Engineer.

• Mentalidad de iteración (Iteration): recorre rápidamente el ciclo despliegue → feedback → ajuste.
• Orientación al cliente: habla directamente con los clientes para mejorar el producto.
• Pragmatismo: «toda elección tecnológica no es más que un medio». Descarta sin dudar las herramientas que no contribuyan al objetivo del producto.

Aquí hay una trampa: es peligroso que el ingeniero especializado en producto sea percibido únicamente como «alguien que construye rápido». Ahora que existe la IA, el riesgo es aún mayor. «Implementar funcionalidades rápidamente» es algo que cualquier otra profesión puede hacer ya con herramientas de IA. La diferencia de un Product Engineer está en «la capacidad de definir con precisión el problema del cliente y validarlo rápidamente con la solución más pequeña», no en «tener manos rápidas».

En esta corriente, la profesión de Design Engineer ha empezado a ascender a la categoría de puesto formal. Vercel está contratando ingenieros de diseño en una vía profesional formal con salarios superiores a 200.000 dólares, y Linear y Stripe avanzan en una dirección similar. Es una profesión que elimina el propio handoff entre frontend y diseño. Como la IA dibuja rápidamente, se ha vuelto más escasa la capacidad de abordar a la vez «qué dibujar y si el resultado encaja en un sistema de diseño coherente».

Orquestador de IA

La vía de especialización en operaciones es la que está cambiando de forma más drástica. En el artículo original de Hwidong Bae se clasificaba como Full-Stack Engineer y se definía como «una persona muy interesada en la estructura, la integración, las pruebas y el despliegue del proyecto, que maneja directamente API e infraestructura sencillas, cubre los vacíos de la organización y mejora los procesos». En el último año o dos, se le ha añadido la función de operar los propios agentes de IA, por lo que el alcance de esta vía está ampliándose rápidamente.

Al resumir las tendencias de 2026, se destacó como concepto central la «orquestación de agentes de programación (Orchestrating Coding Agents)». Significa ir más allá de encargarle algo a una sola IA para diseñar y operar un sistema en el que varios agentes de IA colaboran simultáneamente. En la misma línea, también se propone codificar directamente los flujos de trabajo profesionales, las puertas de calidad y las mejores prácticas del sector en la lógica operativa de los agentes mediante un framework llamado «agent-skills».

Tras reunir los materiales relacionados, estas son, a mi juicio, las nuevas palabras clave que deben manejar los ingenieros de la vía de operaciones.

• MCP (Model Context Protocol): estándar propuesto por Anthropic para conectar los LLM con herramientas externas.
• Gobernanza de IA: gestionar quién puede usar la IA y con qué contexto, y comprobar que no se filtren secretos.
• Evaluación de agentes (Evaluation): pipeline que puntúa automáticamente los resultados producidos por un agente.
• Puerta de IA: verificación automática de seguridad y calidad antes de hacer merge de una PR, y etiquetado del código de IA.

El artículo original proponía como caminos senior de la vía de operaciones puestos como ingeniero de equipo de plataforma en una organización a gran escala / tech lead / coach agile / technical program manager (TPM) / CTO. Esos caminos siguen siendo válidos, pero ahora se les han sumado puestos como «responsable de infraestructura de desarrollo con IA» e «ingeniero de productividad del desarrollador (DevProd)».

Mientras cada una de las tres vías evoluciona por su cuenta, hay competencias que se han vuelto más importantes en todas ellas. En un principio quería pensar a cinco años vista, pero, con la velocidad actual del progreso, incluso un año parece una unidad demasiado grande. Por eso reduciré de momento el horizonte a «el año que viene» y señalaré las competencias que, en mi opinión, cobrarán más importancia.

Cinco competencias

La primera es la capacidad de redactar especificaciones (Specification). En la era de la IA, el «punto de partida de la programación» no es el teclado, sino la especificación. La capacidad de describir con precisión qué se le debe pedir a la IA se ha vuelto más importante que el propio código. Aquí, una especificación no es necesariamente un grandilocuente documento RFC. Puede tratarse de pruebas que expresan en código el comportamiento esperado de la lógica de negocio, de stories de Storybook que recogen los escenarios y el contrato visual de un componente de UI, o de definiciones de tipos que especifican el contrato del flujo de datos. En definitiva, consiste en establecer de antemano criterios que permitan verificar automáticamente lo producido por la IA; si se programa con IA sin ellos, los problemas se acumulan.

La segunda es la capacidad de verificación y el criterio. La IA produce con seguridad código plausible pero incorrecto. Por eso considero esencial «la capacidad de revisar el código de IA con rapidez y precisión». Se trata de detectar si faltan headers de seguridad, sanitization de inputs o tokens CSRF; si siguen funcionando la accesibilidad —ARIA, navegación con teclado y focus traps—; y si existen problemas de rendimiento relacionados con el coste de renderizado, la memoria o el tamaño del bundle. Lanzar AI slop a una PR sin revisarlo es una dejación de funciones como ingeniero. Quien pulsa el botón de merge sigue siendo una persona y no puede trasladar esa responsabilidad a la IA. Es muy probable que, en la encuesta de Stack Overflow, la confianza de los senior en la IA sea la más baja precisamente porque tienen el ojo necesario para detectar estos detalles.

La tercera es la comprensión de sistemas y el pensamiento arquitectónico. La IA maneja bien un archivo cada vez y posee una gran capacidad para reconocer flujos y relaciones. La IA corrige rápidamente los síntomas, pero un buen desarrollador encuentra la causa raíz. Una forma de cultivar esta competencia es realizar actividades deliberadas como una Architecture Retrospective. Como la velocidad de cambio del código ha aumentado, si no se eleva también conscientemente la comprensión del sistema por parte del equipo, la deuda cognitiva se acumula con rapidez.

La cuarta es la capacidad de orquestar IA. El manejo de la propia IA también se está separando como un conjunto específico de competencias. Ya no se trata simplemente de «escribir buenos prompts», sino de abordar como un todo la capacidad de dividir el trabajo en tickets pequeños, elegir qué modelo utilizar para cada tarea, diseñar pipelines de evaluación y verificación de agentes, y definir estrategias de recuperación (rollback) cuando un agente falla. Steve Yegge organiza esta evolución en seis waves (traditional → completions → chat → coding agents → agent clusters → agent fleets).

La quinta es Context Engineering. Es un concepto que Karpathy y Tobi Lütke, CEO de Shopify, empezaron a impulsar juntos a mediados de 2025 y que, en pocas palabras, consiste en «la capacidad de diseñar qué contexto mostrarle a la IA, en qué formato y en qué cantidad». En concreto, adopta formas como el trabajo con archivos CLAUDE.md / rules, donde se documentan las convenciones del proyecto, los principios arquitectónicos y las prohibiciones al alcance de la IA; la reducción deliberada del contexto, que selecciona únicamente los módulos relevantes en lugar de incorporar todos los archivos; la separación explícita de etapas, que divide planificación → implementación → verificación en sesiones distintas para evitar la contaminación del contexto; y el contexto externo mediante MCP, que conecta a través de interfaces estándar fuentes externas como sistemas de diseño, esquemas de API y datos de monitorización. La documentación oficial de Anthropic lo denomina «the new prompt engineering» y afirma categóricamente que un único prompt jamás puede contener el conocimiento arquitectónico, los patrones y la tribal wisdom de un sistema. Dicho de otro modo, «diseñar de una vez un buen prompt» importa mucho menos que «diseñar un entorno en el que la IA reciba siempre un buen contexto».

Llegados hasta aquí, surge una pregunta natural. Entonces, ¿cómo se estudia todo esto en concreto? Los métodos que utilizo son, a grandes rasgos, cuatro.

Cómo aprender

La «formación continua» señalada en el artículo original sigue siendo válida, pero debe cambiar la distribución del tiempo de aprendizaje.

Hay áreas a las que antes dedicábamos mucho tiempo y que ahora podemos reducir. En cambio, también existen ámbitos complejos que antes evitábamos por su dificultad o porque exigían mucho tiempo. Entre estos últimos están la redacción de especificaciones de pruebas, el uso de herramientas de medición del rendimiento (Lighthouse, WebPageTest, Chrome DevTools Performance), la accesibilidad (WCAG) y la seguridad, en especial el OWASP Top 10. Y hay ámbitos completamente nuevos que debemos aprender, como Vercel AI SDK, LangChain.js, MCP, los patrones de UI por streaming y los pipelines de evaluación de agentes. Es importante reconocer qué competencias necesito y distribuir el tiempo en consecuencia.

El código producido por la IA tiende a crecer mucho. Genera cientos de líneas por minuto. Por eso, si no se gestionan conscientemente el tamaño de las PR y el ciclo de merge, la propia revisión de código se viene abajo. Tras la adopción interna de la IA, el tamaño medio de las PR aumentó un 18%, los incidentes por PR un 24% y la tasa de fallos de cambios un 30%. Si relacionamos estas cifras con los datos anteriores, hacer cambios grandes y fusionarlos de una sola vez dificulta comprender el flujo y reflejar la intención, por lo que es importante dividir el trabajo en unidades más pequeñas.

Hay una cuestión directamente relacionada con el problema de la reducción de la carga cognitiva señalado en el artículo de Evan Moon. Conviene reservar una o dos horas al día para escribir código sin IA. Por ejemplo, dibujar la arquitectura a mano o leer personalmente, línea por línea, código de un ámbito poco familiar. (Yo también intento programar sin IA todos los días durante ese sopor que sigue al almuerzo. Es un tiempo que reservo para no alejarme de aquella familiaridad).

No se trata simplemente de «no olvidar la forma antigua». La razón es que la propia profundidad no crece durante el tiempo en que la IA hace el trabajo por uno. Competencias como la verificación, el criterio y la comprensión de sistemas dependen del tiempo dedicado a enfrentarse directamente a los problemas.

Entonces, nosotros

Aunque me he extendido mucho, lo cierto es que el perfil del ingeniero frontend que sobrevive en la era de la IA no difiere tanto de la conclusión del artículo original. Estos eran los tres puntos que allí se atribuían a un buen ingeniero senior.

• Se esfuerza por mantener unos fundamentos sólidos. (Mantiene y refuerza continuamente las cinco competencias básicas).
• Aunque no sea un líder explícito, ejerce una influencia natural mediante una conducta ejemplar.
• No se conforma con terminar bien el trabajo asignado, sino que examina el contexto anterior y posterior y genera un gran impacto.

Aplicado a la era de la IA, quedaría así.

• Mantiene sólidos los fundamentos —web, sistemas y dominio— que hay más allá del código producido por la IA.
• Marca personalmente la dirección, en lugar de dejarla en manos de la IA. Incluso cuando no es la persona responsable explícita, decide «hacia dónde hay que ir».
• No utiliza la IA solo como herramienta de productividad personal, sino para eliminar los cuellos de botella del equipo y del sistema.

Si examinamos los escritos de Andrej Karpathy, una autoridad de Open AI, el núcleo del «agentic engineering» que ahora subraya es, en última instancia, el mismo: diseñar el sistema, especificar las restricciones y usar la IA para acelerar una implementación cuyo razonamiento ya se ha completado mentalmente. Aunque cambien las herramientas, el control de la dirección sigue en manos humanas.

El mensaje final del artículo original también era que se convierte en senior «la persona que no se conforma con terminar bien el trabajo asignado, sino que examina el contexto anterior y posterior y genera un gran impacto». En la era de la IA solo ha cambiado la definición de ese «impacto». Hay quien hace merge de una pantalla creada por la IA en una hora con un «funciona, así que vale», y hay quien dedica treinta minutos más a comprobar hasta qué punto esa pantalla es razonable en términos de accesibilidad, seguridad, rendimiento y coherencia con el sistema. Dentro de un año, se reconocerá como senior al segundo. Sobre la frontera entre el 70% —funcionamiento— y el 30% —aplicación y aprovechamiento—, sobrevivirá quien se sitúe del lado del 30%.

Espero que los ingenieros frontend que lean este artículo también se lleven su propia respuesta a la pregunta «¿qué debo estudiar ahora?». Nadie conoce la respuesta correcta, pero estoy bastante convencido de que, cuanto más programe la IA, más sobrevivirán quienes sepan ver «lo que hay más allá del código». Concluyo con la esperanza de poder volver a escribir dentro de un año sobre cuánto habrá cambiado una vez más este panorama.

(Si dentro de un año este artículo parece demasiado obvio o anticuado, quizá signifique que hemos sabido responder bien).

Referencias

Durante mi trabajo como desarrollador frontend me he preguntado incontables veces: «¿Hasta qué punto debería separar esta lógica?» o «¿En qué unidades debería dividir este componente?». Al principio pensaba que abstraer consistía simplemente en extraer las partes comunes: convertir el código repetido en una función y reunir en una sola pieza los elementos compartidos por componentes similares. Sin embargo, después de ver varias veces cómo el código creado de ese modo se convertía con el tiempo en un monstruo cada vez más difícil de tocar, empecé a replantearme qué significa realmente abstraer.

En este artículo recopilo mis reflexiones sobre la esencia de la abstracción y sobre cómo utilizarla en el desarrollo frontend para crear buen código.

Lo abstracto y la abstracción

Antes de entrar en materia, conviene aclarar qué significan exactamente en programación las palabras «abstracto» y «abstracción». Aunque parecen similares, su naturaleza es bastante distinta.

Lo abstracto (Abstract) es un estado y una propiedad. Cuando decimos que algo «es abstracto», queremos decir que se han omitido los detalles concretos y que solo permanecen los conceptos esenciales. Este es precisamente el sentido de las clases o métodos marcados con la palabra clave abstract en Java o TypeScript: son planos incompletos en los que aún no se ha incorporado una implementación concreta y solo se ha definido la forma esencial.

La abstracción (Abstraction) es un proceso y una acción. Consiste en simplificar un objeto complejo conservando únicamente sus características esenciales y eliminando los detalles innecesarios. Lo importante es que abstraer no significa «agrupar las cosas de cualquier manera», sino definir con precisión una responsabilidad en cada nivel.

En la vida cotidiana, «abstracto» suele utilizarse con el matiz de «ambiguo». En programación, sin embargo, la abstracción persigue justo lo contrario. Su objetivo no es generar ambigüedad, sino crear un nuevo nivel de significado que pueda ser absolutamente preciso. La esencia de la abstracción consiste en conservar la información relevante para un contexto dado y olvidar la que no lo es.

En definitiva, la diferencia puede resumirse así: lo abstracto es «el estado en el que solo queda lo esencial», mientras que la abstracción es «el proceso de dejar solo lo esencial». Al diseñar código llevamos a cabo precisamente ese proceso: conservamos únicamente la interfaz esencial de una implementación compleja y ocultamos el resto.

Entonces, ¿por qué necesitamos esta abstracción en programación?

Por qué necesitamos la abstracción

La razón fundamental por la que necesitamos abstracción en programación es sorprendentemente sencilla: para construir cosas más complejas. Cuando intentamos crear algo más complejo, resulta difícil recordar y manejar todos sus numerosos elementos. Por eso los agrupamos y los convertimos en conceptos abstractos más simples.

React, que los desarrolladores frontend utilizamos a diario, es un buen ejemplo. Para renderizar un solo componente tienen lugar internamente procesos complejos como la creación del Virtual DOM, la reconciliación (Reconciliation) y la manipulación del DOM real. Sin embargo, nosotros solo tenemos que escribir JSX sin preocuparnos por nada de eso, porque React ha abstraído todo ese proceso.

Veamos el siguiente código. Al utilizar el componente UserProfile podemos crear y manejar la UI sin conocer procesos internos complejos como la creación del VDOM o el diffing.

<UserProfile name="jihoon" />

Antes era habitual que un desarrollador frontend configurase Webpack a mano, pero hoy frameworks como Next.js o Vite han abstraído la configuración del bundling. Gracias a ello podemos desarrollar aplicaciones sin conocer el funcionamiento interno del bundler y dedicar ese tiempo a problemas de mayor nivel, como la lógica de negocio o la experiencia de usuario. (Por eso considero que el concepto de abstracción es especialmente importante en el trabajo de un desarrollador frontend).

Ese es, en última instancia, el valor esencial de la abstracción: ocultar la complejidad para que algo parezca sencillo y permitir que cada persona se concentre únicamente en su ámbito. Gracias a ello podemos crear software cada vez más grande y complejo sin que una sola persona tenga que comprenderlo todo.

Pero si la abstracción es tan útil, ¿cuanta más haya, mejor? Pensemos con qué propósito deberíamos abstraer.

Reducir el contexto

Muchos desarrolladores entienden la abstracción como «extraer las partes comunes». No es una definición incorrecta, pero describe solo una de las técnicas para abstraer, no la esencia de la abstracción.

Para mí, la esencia de la abstracción consiste en «reducir al nivel adecuado el contexto que necesita conocer quien lee el código».

Veamos un ejemplo sencillo.

interface Order {
  id: string;
  status: "pending" | "completed";
  amount: number;
}
 
let total = 0;
 
const orders: Order[] = [
  { id: "a", status: "pending", amount: 10000 },
  { id: "b", status: "completed", amount: 5000 },
  { id: "c", status: "completed", amount: 8000 },
];
 
for (let i = 0; i < orders.length; i++) {
  if (orders[i].status === "completed") {
    total += orders[i].amount;
  }
}

Quien lee este código debe entender la inicialización, la condición y el incremento del bucle; el acceso a cada elemento mediante un índice; la bifurcación tras comprobar una condición; y hasta cómo se actualiza la variable acumuladora externa. Sin embargo, lo que el código pretende hacer se resume en una sola frase: «calcular el total de los pedidos completados». Para comprender esa frase hay que mantener a la vez cuatro contextos distintos en la cabeza.

const total = orders
  .filter((order) => order.status === "completed")
  .reduce((sum, order) => sum + order.amount, 0);

Gracias a las abstracciones filter y reduce, el desarrollador solo necesita seguir dos intenciones: «seleccionar únicamente los pedidos completados» y «acumular los importes». El contexto de gestionar índices y declarar y actualizar una variable acumuladora ha desaparecido de la superficie del código.

Podemos ir un paso más allá.

const total = sumCompletedOrders(orders);

Ahora quien lee el código ni siquiera necesita saber que el cálculo se realiza recorriendo un array. Solo queda la intención de negocio: «calcular el importe total de los pedidos completados». Podemos centrarnos no en cómo (How) se calcula, sino en qué (What) se calcula.

Desde esta perspectiva, también podemos ver que el código React que escribimos a diario es una combinación de innumerables abstracciones.

import { css } from "@emotion/css";
import { format } from "date-fns";
 
const TodayHeader = () => {
  const now = new Date(); // Date 객체 생성이라는 복잡한 과정을 추상화
  const formatted = format(now, "yyyy-MM-dd"); // 날짜 포맷팅 로직을 추상화
 
  return (
    <h1
      className={css`
        font-size: 1.8rem;
      `}
    >
      {/* CSS-in-JS 처리 과정을 추상화 */}
      Today is {formatted}
    </h1> // React.createElement를 추상화
  );
};
 
// 그리고 위 모든 것을 다시 추상화
<TodayHeader />;

¿Qué ocurriría si todo el código interno de emotion, date-fns y react estuviera desplegado dentro de este archivo de componente? Sería difícil saber por dónde empezar a leer o distinguir qué parte corresponde a la lógica de negocio y cuál al código de una biblioteca. Como la abstracción oculta de manera adecuada el contexto de cada ámbito, podemos concentrarnos únicamente en la esencia: «mostrar la fecha de hoy».

Entonces, al diseñar código real, ¿en qué dirección deberíamos abordar la abstracción?

Qué significa que el nivel de abstracción sea alto o bajo

Cuando hablamos de abstracción, hay un concepto imprescindible: el nivel de abstracción (Level of Abstraction). ¿Qué significa exactamente que el nivel de abstracción de un código sea «alto» o «bajo»?

El código con un nivel de abstracción bajo se aproxima a los procedimientos concretos que ejecuta el ordenador: parsear directamente una cadena, recorrer un array mediante índices o manipular bytes. Expone sin disimulo cómo (How) funciona.

// 추상화 수준이 낮은 코드
const response = await fetch('/api/users');
const users = await response.json();
const filteredUsers = users.filter(user => user.status === 'active');
 
filteredUsers.forEach(user => {
  const element = document.getElementById(`user-${user.id}`);
  if (element) element.style.display = 'block';
});

El código con un nivel de abstracción alto se expresa en el lenguaje del dominio de negocio o del espacio del problema. Algunos ejemplos son processPayment(order), sendNotification(user, message) o validateUserInput(formData). El código con un nivel de abstracción alto muestra qué (What) hace y oculta cómo lo hace.

En Clean Code, Robert C. Martin condensó esta idea en el principio «un solo nivel de abstracción por función (One Level of Abstraction per Function)». Si dentro de una función se mezclan código de alto y de bajo nivel, quien la lee tiene que decidir en cada línea: «¿Esto forma parte de la lógica esencial o es un detalle de implementación?».

El problema se vuelve evidente al verlo en código real.

// 추상화 수준이 뒤섞인 함수
async function registerUser(name: string, email: string, password: string) {
  // ✅ 높은 수준: 비즈니스 규칙 검증
  validateUserInput({ name, email, password });
  await ensureEmailNotDuplicated(email);
 
  // ❌ 낮은 수준: 비밀번호 해싱 직접 구현
  const encoder = new TextEncoder();
  const data = encoder.encode(password);
  const hashBuffer = await crypto.subtle.digest("SHA-256", data);
  const hashedPassword = Array.from(new Uint8Array(hashBuffer))
    .map((b) => b.toString(16).padStart(2, "0"))
    .join("");
 
  // ✅ 높은 수준: 사용자 저장
  const user = await userRepository.save({ name, email, password: hashedPassword });
 
  // ❌ 낮은 수준: 이메일 전송 직접 구현
  const verifyToken = crypto.randomBytes(32).toString("hex");
  await db.execute(
    "INSERT INTO email_tokens (user_id, token, expires_at) VALUES (?, ?, ?)",
    [user.id, verifyToken, new Date(Date.now() + 86_400_000)]
  );
  await transporter.sendMail({
    from: "noreply@example.com",
    to: user.email,
    subject: "Welcome! Please verify your email",
    html: `<a href="/verify?token=${verifyToken}">Verify your account</a>`,
  });
 
  // ✅ 높은 수준: 환영 이메일 발송
  await sendWelcomeEmail(user);
}

Quien lee esta función comienza siguiendo el contexto de alto nivel basado en reglas de negocio del «flujo de registro de usuarios», pero de repente se ve arrastrado a contextos de bajo nivel como la manipulación de buffers de hash, una consulta SQL y la cadena de una plantilla de correo electrónico. Después vuelve a saltar al alto nivel de sendWelcomeEmail. Cuando el nivel de abstracción sube y baja así, la mente de quien lee también tiene que subir y bajar con él.

Si reescribimos la misma función manteniendo un nivel de abstracción uniforme, el resultado es este.

// 추상화 수준이 일관된 함수
async function registerUser(name: string, email: string, password: string) {
  validateUserInput({ name, email, password });
  await ensureEmailNotDuplicated(email);
 
  const hashedPassword = await hashPassword(password);
  const user = await userRepository.save({ name, email, password: hashedPassword });
 
  await sendVerificationEmail(user);
  await sendWelcomeEmail(user);
}

Todas las instrucciones hablan desde el mismo nivel de abstracción. Cada función de nivel inferior se responsabiliza de cómo se implementa el envío del correo o de qué algoritmo se utiliza para hashear la contraseña. Quien lee esta función solo tiene que concentrarse en un único contexto: «el flujo completo del registro de usuarios».

Martin también denominó esto «la regla descendente (The Stepdown Rule)». Al leer el código de arriba abajo, la visión general debería aparecer arriba y los detalles deberían revelarse conforme descendemos, como en un artículo periodístico.

Kent Beck presentó el mismo principio en Smalltalk Best Practice Patterns mediante el patrón Composed Method. Un método debe componerse únicamente de operaciones situadas en el mismo nivel de abstracción, y cada paso debe expresarse como una llamada a un método de una sola línea.

Al final, todas estas ideas convergen en una sola: una función debe hablar desde un único nivel de abstracción. Solo con respetar esta regla, la legibilidad del código mejora de forma notable.

Entonces, ¿cómo debemos orientar la abstracción? ¿Deberíamos partir de lo concreto o de lo abstracto?

Pensar en la composición de piezas, no en extraer elementos comunes

En OOP se suele recomendar «extraer lo común de los elementos concretos para definir algo abstracto». Este enfoque no es incorrecto en sí mismo, pero creo que, si nos aferramos demasiado a él, corremos el riesgo de crear un diseño prisionero de los requisitos actuales.

Veamos un ejemplo. Supongamos que los requisitos incluyen tres botones, A, B y C, todos azules y redondeados, cuya única diferencia es el texto de la etiqueta. Si diseñamos extrayendo solo lo común, podríamos expresarlo así.

const BlueRoundButton = ({ label }: { label: string }) => {
  return <button className="blue round">{label}</button>;
};

Los requisitos actuales se cumplen a la perfección. Pero unos días después, la persona responsable del producto dice:

«Quiero poder cambiar el color del botón B».

En ese momento, hasta el nombre BlueRoundButton empieza a resultar extraño. Podríamos añadir una prop para el color, pero el diseño era vulnerable a los cambios desde el principio porque partía de una coincidencia concreta: «botones azules y redondeados». (Y este es un caso leve; en la vida real llegan innumerables requisitos sobre la forma, el tamaño y muchos otros aspectos de los botones).

Cuando esta situación se repite, uno acaba entendiendo algo de manera natural: si extraemos elementos comunes de requisitos concretos, es fácil que incluso el resultado abstraído refleje únicamente los requisitos actuales.

Por eso prefiero el enfoque inverso. En lugar de extraer una abstracción de lo concreto, consiste en pensar primero en piezas abstractas y componerlas para crear algo concreto.

Imaginemos que estamos creando un componente de notificaciones toast. El requisito inicial es sencillo: «Cuando termine de guardarse, muestra un breve mensaje informativo en la parte inferior». Si lo abordamos extrayendo elementos comunes, obtendremos algo así.

// 현재 요구사항의 공통 특성에서 출발한 설계
type ToastProps = {
  message: string;
  hasAction?: boolean;
  actionLabel?: string;
  onAction?: () => void;
};
 
const Toast = ({ message, hasAction, actionLabel, onAction }: ToastProps) => (
  <div className="toast">
    <span>{message}</span>
    {hasAction && <button onClick={onAction}>{actionLabel}</button>}
  </div>
);

El requisito actual queda cubierto a la perfección. Pero unos días después se pide «añadir un icono a la izquierda según se trate de un éxito o una advertencia». Se agregan hasIcon e iconName. Poco después llega otro requisito: «También necesitamos un toast con una barra de progreso de subida». Se suma otra prop, progress. Tras repetir varias veces este proceso, Toast termina siendo un componente con más de diez props y reglas ocultas que hay que memorizar sobre qué combinaciones son válidas y cuáles no. (Y, por lo general, esas reglas ni siquiera quedan documentadas en comentarios).

El diseño era vulnerable a los cambios porque desde el principio partía de una imagen concreta de cómo «debe ser un toast» en ese momento.

La historia cambia cuando abordamos el problema mediante la composición de piezas.

// 부품을 조립하는 설계
const Toast = ({ children }: PropsWithChildren) => (
  <div className="toast">{children}</div>
);
 
Toast.Icon = ({ name }: { name: "check" | "warn" | "info" }) => {
  /* ... */
};
 
Toast.Message = ({ children }: PropsWithChildren) => <span>{children}</span>;
 
Toast.Action = ({
  children,
  onClick,
}: PropsWithChildren<{ onClick: () => void }>) => (
  <button onClick={onClick}>{children}</button>
);
 
Toast.Progress = ({ value }: { value: number }) => {
  /* ... */
};
 
// 필요한 부품만 골라 조립한다
<Toast>
  <Toast.Message>저장되었습니다</Toast.Message>
</Toast>;
 
<Toast>
  <Toast.Icon name="check" />
  <Toast.Message>업로드 완료</Toast.Message>
  <Toast.Action onClick={undo}>실행 취소</Toast.Action>
</Toast>;
 
<Toast>
  <Toast.Progress value={0.4} />
  <Toast.Message>파일 전송 중...</Toast.Message>
</Toast>;

Se han separado la esencia inmutable —«un toast es un contenedor ligero para alojar algo»— y el aspecto concreto y propenso a cambiar —«qué contiene»—. Ahora podemos añadir tantas piezas nuevas como queramos o disponer las existentes en combinaciones nuevas sin tocar el interior de Toast. También desaparecen las reglas de validez entre combinaciones de props. Basta con introducir lo que queramos introducir.

Un desarrollador con experiencia podría decir: «¿No bastaría con diseñarlo desde el principio aplicando IoC (inversión de control)?». Es cierto. Pero podemos tomar esa decisión porque, después de innumerables tropiezos en el pasado, hemos desarrollado una intuición sobre «qué partes son más propensas a cambiar».

Si todavía no contamos con esa intuición, partir de la pregunta «¿De qué piezas se compone esta funcionalidad y cómo deberían ensamblarse?» facilita mucho la creación de un diseño abierto al cambio.

Llegados a este punto, surge de forma natural otra pregunta: ¿con qué criterio debemos dividir las piezas y cómo debemos presentarlas al exterior?

Tres claves para una buena abstracción

Pensar en la forma de expresarla

La virtud más importante de un módulo abstraído es que su comportamiento pueda deducirse sin abrir el código fuente. Kent Beck llamó a esto el patrón «nombre que revela la intención (Intention-Revealing Name)» y señaló que, si no podemos asignarle un nombre conciso, deberíamos reconsiderar la propia abstracción.

Disponemos principalmente de dos herramientas para conseguirlo: los nombres y los tipos.

// 도대체 뭘 하는 건지 알 수 없는 함수
function calculate(price: number, rate: number): number;
 
// 이름과 타입만으로 동작을 유추할 수 있는 함수
function calculateDiscountedPrice(originalPrice: number, discountRate: number): number;

Con solo ver el nombre calculateDiscountedPrice, sabemos que recibe el precio original y la tasa de descuento y calcula el precio rebajado; la información de tipos, que indica que recibe valores number y devuelve un number, respalda esa interpretación. No necesitamos conocer la lógica de cálculo aplicada internamente.

En cambio, calculate(price: number, rate: number): number no aporta información sobre qué calcula, así que no podemos prever el resultado. Al final tenemos que abrir el código fuente para poder utilizarla y se pierde la ventaja de la abstracción.

Conviene observar que la propia manera de nombrar refleja el nivel de abstracción. En programación, los nombres de las funciones suelen combinar verbo + sustantivo, y el verbo elegido revela en qué nivel de abstracción opera la función.

Sin embargo, el verbo por sí solo no determina el nivel de abstracción. El sustantivo que lo acompaña —el contexto de dominio— es lo que determina el nivel final.

Hay verbos frecuentes en los niveles de abstracción bajos, como parse, encode, decode, serialize, read, write, push, pop, convert o transform. Estas palabras sugieren transformaciones físicas de los datos o manipulaciones directas de estructuras de datos.

En un nivel intermedio aparecen verbos como get, save, load o validate. Son operaciones técnicas, pero su intención ya resulta visible hasta cierto punto.

En los niveles de abstracción altos se utilizan verbos como register, refund, confirm, cancel o submit. Son palabras propias del dominio de negocio. No revelan en absoluto qué procedimiento técnico ocurre en el interior; solo expresan la acción del usuario o el proceso de negocio.

// 낮은 수준: 기술적 동작이 드러남
function parseJSON(text: string): object;
function encodeBase64(data: Uint8Array): string;
 
// 중간 수준: 의도가 드러나되 기술적 맥락이 남아있음
function getUserById(id: string): Promise<User>;
function validateEmail(email: string): boolean;
 
// 높은 수준: 비즈니스 의도만 드러남
function registerUser(form: RegistrationForm): Promise<User>;
function refundPayment(orderId: OrderId, amount: Money): Promise<Refund>;

En Clean Code, Robert C. Martin afirmó al respecto que «es mejor un nombre largo y descriptivo que uno corto y enigmático». También propuso el principio «usa una palabra por concepto», porque si mezclamos fetch, retrieve y get para operaciones del mismo contexto, quien lea el código se preguntará: «¿Son tres operaciones distintas?».

Este principio se aplica igualmente a los nombres de componentes y hooks de React.

<Button />           
<SearchInput />      
<SubmitOrderButton />

La especificidad del nombre de un componente varía según su nivel de abstracción. Button se utiliza como un primitivo de UI genérico de bajo nivel, mientras que SubmitOrderButton expresa con claridad una intención de negocio de alto nivel.

const handleSubmit = async(data: FormData) => { 
  await registerUser(data);
};
 
<Form onSubmit={handleSubmit} />           

on* es el nombre de la prop que el componente expone al exterior. Desde el código que utiliza el componente se declara «a qué evento reaccionar». handle* es el nombre de la función de implementación que se pasa realmente a esa prop.

const user = useAuth();                  
const [items, setItems] = useCartItems();
const { isOpen, toggle } = useModal();   

Los hooks personalizados utilizan el prefijo use para cumplir las reglas de React y permiten que el componente use el estado o las operaciones que ofrece el hook.

Jeff Atwood, creador de Coding Horror, señaló en una ocasión el problema del sufijo Manager. Un nombre como UrlManager no permite saber en absoluto si mantiene un pool de URL, las valida o las crea. Nombres como UrlBuilder, UrlValidator o UrlPool, que revelan una responsabilidad concreta, son mucho mejores. Un nombre ambiguo puede ser una señal de que la propia responsabilidad del módulo también lo es.

En definitiva, un buen nombre es aquel que indica de inmediato a quien lee en qué nivel de abstracción opera el código.

Diseñar deliberadamente la libertad de las entradas

Al diseñar un módulo abstraído aparece con frecuencia una pregunta: «¿Hasta qué punto debemos dejar abierta la funcionalidad?». Esta decisión cambia considerablemente la experiencia de los desarrolladores que utilizan el módulo.

// 기능이 닫힌 컴포넌트
const Button = ({ children }: {children?: React.ReactNode}) => {
  return <button>{children}</button>;
};
 
// 기능이 완전히 열린 컴포넌트
const Button = (props: ComponentProps<"button">) => {
  return <button {...props} />;
};

El primer botón solo acepta children. No permite configurar onClick, type ni disabled. A cambio, quien lo utiliza no tiene nada que decidir.

El segundo botón acepta todos los atributos del elemento button. Ofrece mucha libertad, pero obliga a quien lo utiliza a decidir cuál de las decenas de props disponibles debe usar. Describo estas situaciones diciendo que «el componente obliga al desarrollador a pensar».

No hay una respuesta única. Debemos encontrar el nivel adecuado según el propósito del módulo y sus usuarios. En el botón base de un sistema de diseño puede ser preferible restringir las Props para mantener la coherencia; en un componente utilitario genérico puede convenir abrirlas para ofrecer flexibilidad.

// 지나치게 닫힌 인터페이스 — 다양한 상황에 대응 불가
<Button onClick={handleSubmit}>제출</Button>
// onClick 외의 이벤트, className, disabled 등을 전달할 방법이 없다
 
// 지나치게 열린 인터페이스 — 의도가 사라짐
<Button {...anyProps} />
// 무엇을 전달해야 하는지 사용자가 직접 파악해야 한다

La amplitud de una abstracción debe decidirse en función de quién la utiliza. Para un usuario que necesita comprender la implementación interna y ejercer un control preciso, es adecuada una interfaz de bajo nivel. En cambio, ofrecer una interfaz demasiado abierta a quien no necesita conocer los detalles solo añade confusión. Y, a la inversa, si restringimos en exceso las entradas de alguien que debe responder a situaciones variadas, impediremos los propios casos de uso.

Mantener una unidad de abstracción adecuada

La unidad de abstracción —es decir, «hasta dónde agrupar en un solo módulo»— también es una decisión importante.

Un antipatrón frecuente en frontend es la extracción excesiva de Custom Hooks.

// 이 훅은 단 하나의 컴포넌트에서만 사용된다
const useUserProfileData = () => {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(true);
 
  useEffect(() => {
    fetchUser()
      .then(setUser)
      .finally(() => setLoading(false));
  }, []);
 
  return { user, loading };
};

Si separamos innecesariamente en un hook una lógica que solo utiliza un componente, obligamos a quien lee el código a saltar entre dos archivos para comprender el contexto. En lugar de reducirlo, la abstracción lo ha aumentado.

El extremo contrario —incluir demasiadas cosas en un solo hook— también supone un problema.

// 관련 없는 관심사가 하나의 훅에 뒤섞여 있다
const useEverything = () => {
  const auth = useAuth();
  const theme = useTheme();
  const analytics = useAnalytics();
  const toast = useToast();
 
  return { auth, theme, analytics, toast };
};

Este tipo de «God Hook» es difícil de probar, y modificar un elemento puede afectar a partes que no guardan relación con él.

El criterio para determinar una unidad de abstracción adecuada es «¿Esta separación reduce realmente el contexto de quien lee el código?». Si, como resultado de la separación, el contexto queda disperso y cuesta más comprenderlo, todavía no ha llegado el momento de esa abstracción.

Cuidado con las abstracciones prematuras

Después de leer hasta aquí puede quedar una pregunta: «Entonces, ¿cuándo debemos abstraer?». Mi opinión es la siguiente: la premisa básica debe ser no abstraer de forma prematura.

Mientras no aparezca una señal clara para abstraer, dejar el código tal como está suele ofrecer un resultado mínimo mejor que crear una abstracción incorrecta y tener que deshacerla después. El proceso por el que surge una mala abstracción suele parecerse a este:

1. Aparece un patrón similar en el código A y el código B.
2. Pensamos: «¡El principio DRY dice que debo extraerlo a una función común!» y lo abstraemos.
3. Encontramos un patrón parecido en el código C y usamos la misma función, pero añadimos un parámetro para introducir un comportamiento ligeramente distinto.
4. Al empezar a utilizarla también en el código D y E, siguen aumentando las condiciones y los parámetros.
5. La función ya se utiliza en todas partes, pero se ha convertido en un código que nadie se atreve a tocar.

// 처음에는 단순했던 함수가...
const formatUserName = (user: User) => `${user.firstName} ${user.lastName}`;
 
// 요구사항이 추가될 때마다 매개변수가 늘어나고...
const formatUserName = (
  user: User,
  includeMiddleName?: boolean,
  format?: "full" | "short" | "initials",
  locale?: string,
  honorific?: boolean,
) => {
  if (format === "initials") {
    /* ... */
  }
  if (includeMiddleName && user.middleName) {
    /* ... */
  }
  if (honorific && locale === "ko") {
    /* ... */
  }
  // ...끝없는 분기
};

Si hemos caído en esta situación, la solución está clara: volver a poner inline el código abstraído en cada lugar donde se utiliza, eliminar en cada caso el código innecesario y, cuando el estado quede limpio, abstraer de nuevo si entonces aparece una coincidencia real. «La forma más rápida de avanzar es volver atrás».

Entonces, ¿cuándo debemos abstraer? Estas son, a grandes rasgos, las señales de abstracción que percibo:

• Se está perdiendo la coherencia. Aunque se trata de la misma lógica, en algunos componentes aparece inline y en otros se ha separado en una función. La misma lógica de cálculo está dispersa por todas partes.
• La estructura interna se expone innecesariamente al exterior. Quien llama al módulo tiene que manejar uno por uno detalles de implementación que no necesita conocer.
• El procedimiento interno sigue quedando expuesto. El módulo no logra ocultar su propio procedimiento y quien lo utiliza debe seguirlo tal cual.

El problema es que detectar estas señales suele ser bastante sencillo, pero en la práctica es fácil ignorarlas y centrarse en satisfacer requisitos más «importantes». Cuando nos presionan los plazos o estamos absortos en implementar una funcionalidad, pensamos: «Ya funciona; lo ordenaré más adelante». Y ese momento rara vez llega.

Hay otra cuestión importante: mantener criterios de abstracción coherentes. Si dentro del mismo código base una misma clase de lógica aparece inline en un lugar, como función en otro y como hook personalizado en un tercero, quien lea ese código por primera vez se preguntará: «¿Hay una intención detrás de esta diferencia?». Tanto si se abstrae como si no, el equipo debe aplicar criterios coherentes.

También merece la pena recordar en este contexto «la ley de las abstracciones con fugas (The Law of Leaky Abstractions)», formulada por Joel Spolsky en 2002. Esta ley sostiene que, aunque una abstracción intenta ocultar una implementación compleja, sus detalles terminan filtrándose al exterior (leak). Es decir: algo se diseña para que el usuario de la abstracción no necesite conocer la implementación interna, pero en la práctica surgen situaciones en las que solo puede utilizarla correctamente si la conoce.

TCP abstrae una red inestable para hacerla parecer una conexión fiable, pero la abstracción se rompe si se desconecta el cable. React abstrae de forma declarativa las actualizaciones de la UI, pero para optimizar los rerenderizados acabamos necesitando comprender su funcionamiento interno. Como no existen abstracciones perfectas, al abstraer debemos plantearnos incluso «¿Puede el usuario responder cuando esta abstracción se rompa?».

En definitiva, «la abstracción nos ahorra tiempo de trabajo, pero no tiempo de aprendizaje».

La abstracción se interioriza con la práctica

En una ocasión hablé con un compañero sobre la abstracción y hubo una idea que me resultó especialmente memorable: detectar las señales de abstracción y separar algo en el nivel adecuado y en el momento oportuno pertenece, en última instancia, al terreno de la intuición.

Por supuesto, los principios mencionados antes —mantener el nivel de abstracción, elegir buenos nombres y diseñar la libertad de las entradas— son importantes. Sin embargo, intentar recordar cada uno mientras escribimos código y preguntarnos constantemente «¿Debería separar esto o no?» puede llegar a romper el flujo. Igual que, si durante un combate somos demasiado conscientes del ángulo del codo al lanzar un jab, podemos perder el momento preciso, al programar la abstracción debe surgir de una intuición natural y no de un juicio consciente.

Hay momentos en los que estamos escribiendo código y, de pronto, algo nos produce rechazo. Sentimos: «Esta lógica no debería estar aquí» o «Este componente parece saber demasiado». Esa sensación es precisamente una señal de abstracción; interiorizarla significa poder detectarla y responder a ella de forma natural.

Pero esta intuición no se desarrolla de la noche a la mañana. Solo después de aprender multitud de patrones, leer código diverso y sufrir nuestros propios tropiezos empieza a surgir con naturalidad la sensación de «creo que esto debería separarse». Si más tarde un compañero pregunta «¿Por qué lo separaste?» y podemos explicar con naturalidad «Lo separé porque es X», entonces lo hemos interiorizado.

Creo que ocurre lo mismo en cualquier disciplina. Intentar hacerlo bien a base de memorizar puede dificultar aún más las decisiones. Al final, hay que conservar el flujo general y dejar que los detalles se completen de forma natural. Y esa naturalidad nace de la variedad de patrones y experiencias acumulados en el día a día.

Conclusión

En programación, abstraer es ocultar la complejidad para que algo parezca sencillo y permitir que quien lee el código se concentre únicamente en el contexto que necesita.

Recapitulemos lo que conviene recordar para construir buenas abstracciones:

• Como principio básico, evitemos abstraer de forma prematura y separemos solo cuando aparezca una señal clara.
• Hagamos que una función hable desde un único nivel de abstracción.
• Expresemos suficientemente el comportamiento mediante nombres y tipos para que pueda utilizarse sin abrir el código fuente.
• Diseñemos deliberadamente la libertad de las entradas según el propósito del módulo y sus usuarios.
• En vez de seguir añadiendo capas sobre una abstracción incorrecta, tengamos el valor de deshacerla y empezar de nuevo.
• E interioricemos distintos patrones hasta que todo esto surja de forma natural, sin necesidad de pensarlo conscientemente.

Por supuesto, lo que he expuesto en este artículo no es la única respuesta correcta. El nivel adecuado de abstracción puede variar según la situación del negocio, la composición del equipo y la naturaleza del proyecto. Sin embargo, hay algo que no cambia: el objetivo último de la abstracción es crear código que las personas puedan comprender con facilidad.

Espero que quienes lean este artículo se planteen también en sus propios códigos base la pregunta: «¿Esta abstracción está reduciendo realmente el contexto?». Creo que esa sola pregunta puede cambiar, aunque sea un poco, la forma de mirar el código.

Referencias

Este artículo se inspira en gran medida en distintos documentos oficiales y artículos anteriores. Dejo también las fuentes de las citas directas y los textos que me ayudaron a estructurar estas ideas.

Al usar TanStack Query en proyectos reales, he tenido que replantear varias veces la forma de gestionar queryKey. Al principio escribía directamente en los componentes arreglos como ['user', userId], pero, cada vez que tenía que invalidar una consulta, acababa repitiendo la misma clave en varios lugares y cometiendo errores tipográficos. Por eso las trasladé a un objeto de constantes como QUERY_KEYS. Más adelante, tras leer un artículo de TkDodo, adopté el patrón de fábrica de claves de consulta; bastante tiempo después incorporé la librería @lukemorales/query-key-factory; y, cuando apareció v5, volví a reorganizarlo todo en torno a queryOptions.

Empecé a preguntarme por qué habían surgido tantos patrones alrededor de un pequeño arreglo que, en principio, no era más que un identificador de caché. ¿Por qué queryKey conserva tantas huellas de esa evolución? ¿Y qué problema concreto intentaba resolver cada etapa?

En este artículo seguiré la documentación oficial de TanStack Query, la serie de artículos de TkDodo y hasta la implementación interna de queryOptions introducida en v5 para explicar cómo funciona queryKey y por qué ha evolucionado hasta adoptar su forma actual.

Antes de que existiera queryKey

Antes de entrar de lleno en el tema, conviene detenernos en una cuestión. Hoy usamos con total naturalidad librerías como TanStack Query y SWR, pero ¿cómo se gestionaban los datos asíncronos antes de que existieran?

La forma más habitual probablemente consistía en combinar useState, useEffect, fetch, axios y herramientas similares.

function UserProfile({ userId }: { userId: string }) {
  const [user, setUser] = useState<User | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<Error | null>(null);
 
  useEffect(() => {
    let cancelled = false;
    setLoading(true);
 
    fetch(`/api/users/${userId}`)
      .then((res) => res.json())
      .then((data) => {
        if (!cancelled) setUser(data);
      })
      .catch((err) => {
        if (!cancelled) setError(err);
      })
      .finally(() => {
        if (!cancelled) setLoading(false);
      });
 
    return () => {
      cancelled = true;
    };
  }, [userId]);
 
  // ...
}

El problema de este código es evidente. Basta con que haya dos componentes en la página mostrando el mismo userId para que la misma petición se envíe dos veces. La razón es que no existe una caché. Además, si el usuario visita otra página y después regresa, los datos vuelven a solicitarse desde cero. Como no hay forma de distinguir si se obtuvieron hace un segundo o hace una hora, también resulta difícil reproducir comportamientos como «mostrar el valor almacenado en caché mientras se actualiza en segundo plano». (Podríamos implantar nuestro propio sistema de caché, pero considero que gestionarlo sería bastante complicado.)

Para resolverlo apareció la combinación Redux + redux-thunk (o redux-saga). Al extraer la lógica de obtención de datos a un thunk y guardar el resultado en el almacén, otros componentes podían reutilizar los mismos datos. Sin embargo, había que definir tipos de acción, escribir reductores y gestionar manualmente los estados de carga, éxito y error en cada ocasión. La cantidad de código repetitivo necesaria para obtener un solo dato era enorme. (Empecé a trabajar profesionalmente en esa época y me preguntaba: «¿Por qué tengo que crear varios archivos para obtener un único dato?».)

En el fondo, todo este recorrido se reduce a lo siguiente: «Para evitar repetir una petición, debemos poder identificar de qué petición se trata». Y el identificador que responde a «de qué petición se trata» es precisamente queryKey.

SWR y React Query (hoy TanStack Query) abordaron el problema de frente: «Toda petición asíncrona debe tener un identificador y, si el identificador es el mismo, debe compartir la caché». Este único y sencillo principio eliminó todo el código repetitivo anterior.

La esencia de queryKey

Entonces, ¿qué es exactamente queryKey? La documentación oficial de TanStack Query lo define así.

En esencia, TanStack Query gestiona el almacenamiento en caché de las consultas a partir de sus claves. En el nivel superior, las claves de consulta deben ser un arreglo... Siempre que la clave de consulta se pueda serializar y sea exclusiva de los datos de la consulta, puede utilizarse.

At its core, TanStack Query manages query caching for you based on query keys. Query keys have to be an Array at the top level... As long as the query key is serializable, and unique to the query's data, you can use it.

Hay dos ideas esenciales: debe poder serializarse y debe ser exclusiva de esos datos. Una misma clave representa los mismos datos, y datos distintos deben tener claves distintas. Esta sencilla regla determina el funcionamiento de todo el sistema de caché.

Hay, además, otro aspecto importante: queryKey actúa al mismo tiempo como arreglo de dependencias. Del mismo modo que en useEffect de React el efecto vuelve a ejecutarse cuando cambian sus dependencias, cuando cambia queryKey TanStack Query obtiene automáticamente los datos nuevos.

const { data } = useQuery({
  queryKey: ['user', userId],
  queryFn: () => fetchUser(userId),
});

Cuando userId es 'A' y cuando es 'B', las queryKey son diferentes. Si son diferentes, se produce un fallo de caché; si hay un fallo de caché, se obtienen los datos. Todo ocurre automáticamente. Gracias a esta sencillez, no tenemos que escribir por nuestra cuenta la lógica de «como userId ha cambiado, hay que volver a obtener los datos».

Aquí surge una pregunta: ¿cómo determina TanStack Query que dos queryKey son «la misma clave»? Si las comparase simplemente con ===, las referencias de los objetos serían distintas y se produciría un fallo de caché en cada ocasión.

El interior de QueryCache

Según El interior de React Query, de TkDodo, QueryCache no es más que una estructura de datos mantenida en memoria. Para ser más precisos, en la implementación oficial de v5 esa estructura no es un objeto plano, sino un Map<string, Query>. Dentro de la clase se declara como #queries = new Map<string, Query>(), y todas las escrituras y lecturas se realizan mediante #queries.set(query.queryHash, query) y #queries.get(queryHash). La clave es la forma serializada de queryKey (queryHash), y el valor es una instancia de la clase Query.

En versiones antiguas también se utilizaron objetos planos, pero en v5 se adoptó el Map nativo. (Map evita las colisiones de claves y el riesgo de contaminación del prototipo, conserva el orden de inserción y ofrece búsquedas por clave de cadena con una complejidad media de O(1), por lo que es una elección casi canónica para una estructura de caché.)

Lo que ocurre cada vez que se llama a useQuery es sencillo: queryKey se convierte en un valor hash y este se utiliza para buscar en el mapa. Si existe, se recupera la instancia de Query almacenada en caché; si no, se crea una nueva y se guarda con set.

De aquí se desprende otra pregunta natural: ¿por qué serializar queryKey como una cadena? ¿No bastaría con usar el propio arreglo como clave, como en Map<QueryKey, Query>?

La respuesta está en el modelo de igualdad de JavaScript. El Map nativo compara sus claves mediante igualdad referencial (reference equality). Aunque el contenido sea el mismo, considera diferentes dos objetos que ocupan lugares distintos en memoria.

const m = new Map();
m.set(['user', 1], 'alice');
m.get(['user', 1]); // undefined — 새로 만든 배열은 다른 참조다

Sin embargo, en un componente de React, useQuery({ queryKey: ['user', userId] }) crea una nueva instancia del arreglo en cada renderizado. Aunque los arreglos queryKey del primer y del segundo renderizado tengan el mismo contenido, son objetos distintos en memoria. Si la caché dependiera de la igualdad referencial, cada renderizado de un componente que mostrase los mismos datos provocaría un fallo de caché.

La solución al problema causado por la igualdad referencial es sencilla: convertir la igualdad referencial en igualdad estructural (structural equality). Se genera una cadena determinista basada únicamente en el contenido de queryKey y se usa esa cadena como clave del mapa. Así se recupera la semántica deseada: «si el contenido es igual, la clave es igual». JSON.stringify no es más que la herramienta más sencilla para realizar esa conversión. (Esta es también la razón por la que TanStack Query, tras probar varias estrategias de serialización durante la época de v3, terminó adoptando una variante estable de JSON.stringify.)

La pieza central es la función que genera ese valor hash: hashKey. La implementación oficial, definida en packages/query-core/src/utils.ts, es exactamente esta.

export function hashKey(queryKey: QueryKey | MutationKey): string {
  return JSON.stringify(queryKey, (_, val) =>
    isPlainObject(val)
      ? Object.keys(val)
          .sort()
          .reduce((result, key) => {
            result[key] = val[key]
            return result
          }, {} as any)
      : val,
  )
}

Utiliza JSON.stringify, pero no sin más: introduce una función de reemplazo que ordena alfabéticamente las claves de los objetos planos antes de serializarlos.

Este ordenamiento es esencial porque la serialización a una cadena impone otra condición aún más estricta: las entradas semánticamente iguales deben convertirse siempre en la misma cadena. Sin embargo, JSON.stringify normal conserva el orden de las claves. Aunque { a: 1, b: 2 } y { b: 2, a: 1 } sean objetos semánticamente iguales, se serializan como cadenas diferentes y terminan ocupando espacios de caché distintos. Así volverían a solicitarse dos veces los mismos datos.

La técnica que evita sistemáticamente este problema es la forma canónica (canonical form). Consiste en obligar a que las entradas semánticamente iguales correspondan siempre a una única representación. Ese es exactamente el motivo por el que la función de reemplazo de hashKey ordena las claves de los objetos planos. Hace que el resultado sea idéntico con independencia del orden de entrada, de modo que el resultado de la serialización quede vinculado de manera unívoca al significado del objeto. En términos matemáticos, selecciona la forma ordenada como elemento representativo de la clase de equivalencia (equivalence class) formada por objetos cuyas claves tienen órdenes distintos.

El hecho de que los arreglos no se ordenen es la otra cara del mismo principio. En un arreglo, el propio orden contiene significado; ordenarlo supondría perder información. El orden de las claves de un objeto es accidental, mientras que el orden de los elementos de un arreglo es intencionado. hashKey trata ambos casos de forma deliberadamente distinta. Por eso la guía oficial recomienda organizar queryKey de «lo genérico a lo específico». Mientras el orden del arreglo aporte significado, el autor debe definirlo expresamente.

Hay otro detalle que conviene señalar: el ordenamiento de claves solo se aplica a los objetos planos. isPlainObject, definida en el mismo archivo, no se limita a comprobar typeof === 'object', sino que verifica incluso Object.getPrototypeOf(o) === Object.prototype para distinguir entre literales de objeto puros e instancias de clase. Por eso un literal como { foo: 1 } se ordena, mientras que una instancia creada con class User { ... } pasa sin ordenarse. (De aquí surge el riesgo de que, si se introduce directamente una instancia de clase en queryKey, se genere un hash distinto del esperado debido a que JSON.stringify solo emite las propiedades enumerables.)

Este funcionamiento tiene dos consecuencias importantes.

1. El orden de las claves de un objeto es irrelevante.

useQuery({ queryKey: ['todos', { status: 'done', page: 1 }], queryFn });
useQuery({ queryKey: ['todos', { page: 1, status: 'done' }], queryFn });
// 두 쿼리는 같은 캐시 슬롯을 공유한다

La razón es que las claves se ordenan antes de serializarse. Sin este proceso, al escribir un literal de objeto habría que recordar siempre el orden de sus claves.

2. El orden de los elementos de un arreglo sí importa.

useQuery({ queryKey: ['todos', status, page], queryFn });
useQuery({ queryKey: ['todos', page, status], queryFn });
// 두 쿼리는 다른 캐시이다

Esto se debe a que un arreglo es una estructura de datos en la que el propio orden tiene significado. JSON.stringify también conserva el orden de los arreglos.

También conviene saber que los valores undefined desaparecen durante la serialización. { a: 1, b: undefined } y { a: 1 } generan el mismo hash. (Yo mismo cometí una vez el error de pensar: «¡Como he añadido undefined de forma explícita, será otra caché!».)

Además, queryKey no puede contener referencias circulares ni funciones, porque JSON.stringify no puede procesarlas. Por el mismo motivo, tampoco se recomienda utilizar con su comportamiento predeterminado objetos Date, Map/Set, BigInt y similares. Debe ser una estructura de datos pura y serializable.

Lo interesante es que esta restricción no se impone por completo. Mediante la opción queryKeyHashFn, TanStack Query ofrece una vía de escape que permite sustituir la propia función hash. Internamente, hashQueryKeyByOptions(queryKey, options) comprueba si las opciones incluyen queryKeyHashFn: si existe, la llama; si no, utiliza la función hashKey predeterminada.

useQuery({
  queryKey: [{ id: userId, fetchedAt: new Date() }],
  queryFn,
  // Date를 ISO 문자열로 바꿔서 해싱
  queryKeyHashFn: (key) =>
    JSON.stringify(key, (_, v) => (v instanceof Date ? v.toISOString() : v)),
});

Sin embargo, esta opción debe configurarse por separado para cada consulta y no se aplica en API imperativas como queryClient.setQueryData, que se invocan sin conocer esas opciones (incidencia n.º 1343). Por eso, en la práctica es mucho más seguro evitar esta vía de escape y convertir queryKey a una forma serializable en el momento de crearla. (Yo también introduje una vez un Date directamente y pasé bastante tiempo preguntándome: «¿Por qué no se actualiza la caché si es el mismo instante?». La respuesta final fue: «Ese Date representa el mismo instante, pero es otra instancia de objeto y genera un hash distinto cada vez».)

Reglas para escribir queryKey

Una vez comprendido el complejo funcionamiento interno anterior, las reglas de escritura se deducen de forma natural. Las recomendaciones de la documentación oficial pueden resumirse así.

Regla 1. queryKey debe ser siempre un arreglo.

Aunque pasar una cadena también funciona (internamente se convierte en un arreglo), conviene usar un arreglo desde el principio para mantener la coherencia.

// 비권장
useQuery({ queryKey: 'todos', queryFn });
 
// 권장
useQuery({ queryKey: ['todos'], queryFn });

Regla 2. Incluye en queryKey todas las variables de las que depende queryFn.

// 잘못된 예: userId가 쿼리키에 없다
useQuery({
  queryKey: ['user'],
  queryFn: () => fetchUser(userId),
});
 
// 올바른 예
useQuery({
  queryKey: ['user', userId],
  queryFn: () => fetchUser(userId),
});

Es la misma forma de pensar que con las dependencias de useEffect. Todas las variables utilizadas dentro de la función deben formar parte de la clave (= dependencia). Si se incumple esta regla, pueden aparecer errores difíciles de rastrear, como que los datos del usuario anterior sigan mostrándose después de cambiar a otro usuario.

Regla 3. Organiza los elementos desde el más genérico hasta el más específico.

// 좋다
['todos', 'list', { filter: 'done' }]
['todos', 'detail', todoId]
 
// 안 좋다 (순서가 뒤집혀 있음)
[{ filter: 'done' }, 'list', 'todos']

Este orden es importante por la invalidación (invalidation). De forma predeterminada, invalidateQueries de TanStack Query utiliza coincidencia por prefijo.

// 모든 todos 관련 쿼리 무효화
queryClient.invalidateQueries({ queryKey: ['todos'] });
// → ['todos', 'list', ...], ['todos', 'detail', ...] 모두 매치된다
 
// list 쿼리만 무효화
queryClient.invalidateQueries({ queryKey: ['todos', 'list'] });
// → ['todos', 'list', ...]만 매치된다

Si las claves se diseñan como una estructura de árbol, se puede expresar en una sola línea desde «vuelve a obtener todos los datos de este dominio» hasta «vuelve a obtener únicamente este elemento concreto». (A primera vista puede parecer poco importante, pero su valor se vuelve evidente después de diseñarlo mal una vez y comprobar que el alcance de la invalidación no se comporta como esperabas.)

Evolución de la gestión de queryKey

Hasta aquí hemos visto el funcionamiento y el uso de queryKey. Pasemos ahora a la pregunta principal: ¿cómo ha ido cambiando su gestión?

Voy a ordenar cronológicamente las etapas por las que he pasado en proyectos reales.

1. Arreglos en línea

Es la forma más sencilla. Dentro del componente se combinan cadenas fijas con valores de las propiedades.

function UserProfile({ userId }: { userId: string }) {
  const { data } = useQuery({
    queryKey: ['user', userId],
    queryFn: () => fetchUser(userId),
  });
  // ...
}
 
function PostList({ filter }: { filter: PostFilter }) {
  const { data } = useQuery({
    queryKey: ['posts', filter],
    queryFn: () => fetchPosts(filter),
  });
  // ...
}

Al comenzar, esto puede ser suficiente.

El problema aparece cuando crece la base de código. Hay que invalidar desde una mutación que modifica la información del usuario, pero cada vez es necesario buscar «¿cuál era la clave de las consultas relacionadas con usuarios?». Unos lugares utilizan ['user', userId] y otros ['users', userId] (en plural). Como ocupan espacios de caché completamente distintos, la invalidación solo se aplica a uno de ellos.

2. Objeto de constantes

Para evitar errores tipográficos, las claves de consulta se agrupan como constantes.

// queryKeys.ts
export const QUERY_KEYS = {
  USER: 'user',
  POSTS: 'posts',
  COMMENTS: 'comments',
} as const;
 
// 사용처
useQuery({
  queryKey: [QUERY_KEYS.USER, userId],
  queryFn: () => fetchUser(userId),
});

Los errores tipográficos desaparecen, pero la responsabilidad de componer la clave sigue recayendo en cada lugar de uso. Alguien escribe la combinación [QUERY_KEYS.USER, userId] como [QUERY_KEYS.USER, userId, 'detail'], mientras que otra persona usa ['user', 'detail', userId]. Llega un momento en el que hay que memorizar por separado qué convención es la correcta.

3. Fábrica de claves de consulta

Este patrón quedó concretado en el artículo Claves eficaces para React Query, de TkDodo. Consiste en definir un objeto que crea las claves de cada dominio y expresar la jerarquía mediante funciones.

// features/todos/queries.ts
const todoKeys = {
  all: ['todos'] as const,
  lists: () => [...todoKeys.all, 'list'] as const,
  list: (filters: string) => [...todoKeys.lists(), { filters }] as const,
  details: () => [...todoKeys.all, 'detail'] as const,
  detail: (id: number) => [...todoKeys.details(), id] as const,
};
 
// 사용
useQuery({ queryKey: todoKeys.detail(1), queryFn: ... });
useQuery({ queryKey: todoKeys.list('done'), queryFn: ... });
 
// 무효화
queryClient.invalidateQueries({ queryKey: todoKeys.all });        // 전체
queryClient.invalidateQueries({ queryKey: todoKeys.lists() });    // 모든 리스트
queryClient.invalidateQueries({ queryKey: todoKeys.detail(1) });  // 특정 항목

Este patrón es potente porque la jerarquía queda expresada de forma explícita en el código. todoKeys.all apunta a todas las consultas relacionadas con tareas, todoKeys.lists() a todas las consultas de tipo lista y todoKeys.detail(1) a un elemento concreto. El alcance de la invalidación puede expresarse con precisión en una línea de código.

Otra ventaja es la colocación conjunta (co-location). TkDodo no recomienda reunir las claves en un archivo global. En su lugar, propone colocar queries.ts dentro del directorio de la funcionalidad y mantener allí tanto las claves como los hooks.

src/
└── features/
    └── todos/
        ├── index.tsx
        └── queries.ts   # 키와 훅을 모두 여기에

Así se obtiene un modelo mental sencillo: «para modificar algo relacionado con tareas, basta con mirar la carpeta de tareas». Es una aplicación fiel del principio de mantener juntas las cosas que cambian juntas.

4. @lukemorales/query-key-factory

Al escribir manualmente una y otra vez el tercer patrón, el código repetitivo se acumula. Además, cuando se quieren combinar y gestionar las claves de varios dominios, se echa en falta una interfaz normalizada. @lukemorales/query-key-factory es el resultado de convertir este patrón en una librería.

import { createQueryKeys, mergeQueryKeys } from '@lukemorales/query-key-factory';
 
const users = createQueryKeys('users', {
  detail: (userId: string) => ({
    queryKey: [userId],
    queryFn: () => api.getUser(userId),
  }),
  list: (filters: UserFilters) => ({
    queryKey: [{ filters }],
    queryFn: () => api.getUsers(filters),
  }),
});
 
const todos = createQueryKeys('todos', {
  detail: (id: number) => ({
    queryKey: [id],
    queryFn: () => api.getTodo(id),
  }),
});
 
export const queries = mergeQueryKeys(users, todos);
 
// 사용
useQuery(queries.users.detail('abc'));
useQuery(queries.todos.detail(1));
 
// 무효화
queryClient.invalidateQueries(queries.users._def);            // 모든 user 쿼리
queryClient.invalidateQueries(queries.users.detail('abc'));   // 특정 항목

createQueryKeys añade automáticamente el prefijo, y mergeQueryKeys permite combinar dominios. Además, la propiedad convenida _def da acceso a la clave de todo el dominio. Desaparece así la necesidad de añadir as const en cada fábrica manual para restringir los tipos por cuenta propia.

Durante un tiempo, esta librería se utilizó prácticamente como un estándar. (Yo también la usé con frecuencia durante bastante tiempo.) Sin embargo, la aparición de queryOptions cambió la situación.

5. queryOptions (API oficial de v5)

Uno de los cambios más importantes de TanStack Query v5 fue la introducción de la API queryOptions. Con el paso de v4 a v5, los argumentos de todos los hooks se unificaron en un único objeto. El verdadero propósito de ese cambio era permitir extraer ese objeto como unidad reutilizable.

import { queryOptions } from '@tanstack/react-query';
 
export const userDetailOptions = (userId: string) =>
  queryOptions({
    queryKey: ['user', userId],
    queryFn: () => fetchUser(userId),
    staleTime: 5 * 60 * 1000,
  });
 
// 어디서나 사용 가능
useQuery(userDetailOptions('abc'));
useSuspenseQuery(userDetailOptions('abc'));
queryClient.prefetchQuery(userDetailOptions('abc'));
queryClient.setQueryData(userDetailOptions('abc').queryKey, newUser);

A primera vista puede surgir la duda: «¿Qué tiene esto de diferente? Parece simplemente un objeto envuelto en una función». TkDodo también lo reconoce en su artículo La API Query Options. Durante la ejecución, se limita realmente a devolver el mismo objeto que recibe.

El trabajo verdaderamente útil ocurre dentro del sistema de tipos. Veámoslo a continuación.

DataTag de queryOptions

queryOptions no es una simple función auxiliar porque incorpora información sobre el tipo de los datos en la queryKey devuelta. Dentro de TanStack Query, este mecanismo se denomina DataTag.

Su implementación aproximada es la siguiente.

declare const dataTagSymbol: unique symbol;
declare const dataTagErrorSymbol: unique symbol;
 
export type DataTag<TType, TValue, TError = unknown> = TType & {
  [dataTagSymbol]: TValue;
  [dataTagErrorSymbol]: TError;
};

Se trata de un tipo con marca (branded type) basado en unique symbol. Es solo una marca sin ningún efecto durante la ejecución, pero para TypeScript contiene la información de que «este arreglo no es un simple arreglo, sino un arreglo asociado a datos del tipo TValue».

Existe una razón concreta para utilizar unique symbol. El artículo de Zenn El unique symbol que se oculta tras DataTag compara este recurso con «una plaza de aparcamiento exclusiva para la información de tipos». Si se utilizase una clave de cadena normal, podría colisionar con una clave de otra librería o del código del usuario; sin embargo, cada declaración unique symbol crea por sí misma un tipo único, por lo que nunca coincide con otra declaración. Se convierte así en un identificador que no puede colisionar.

La diferencia que produce este único mecanismo es considerable.

const data = queryClient.getQueryData(['user', 'abc']); // unknown
const data = queryClient.getQueryData(userDetailOptions('abc').queryKey); // User | undefined

Aunque getQueryData y setQueryData solo reciben una queryKey, como esta ya lleva incorporado el tipo de datos, el tipo devuelto se infiere automáticamente. No es necesario proporcionar los genéricos a mano y, si se intenta introducir en setQueryData un valor de un tipo incorrecto, el compilador lo detecta de inmediato.

Por supuesto, también existen limitaciones. En métodos como getQueriesData, que obtienen varias consultas a la vez, el resultado es un arreglo de tuplas heterogéneas y no se aplica la inferencia de tipos. Además, el uso de unique symbol puede provocar un error TS4023 al generar archivos .d.ts en un monorepositorio; se evita importando dataTagSymbol de forma explícita.

Al resumir el mecanismo visto hasta aquí, queda claro un hecho: la inferencia de tipos de queryOptions depende por completo de que queryKey y queryFn se declaren juntas en un mismo lugar. Para incorporar en queryKey el tipo que devuelve queryFn, ambas deben declararse juntas.

Esto tiene una implicación de peso para la dirección de diseño de las fábricas de claves de consulta. Los patrones de la generación anterior se centraban en separar la gestión de queryKey como una unidad de abstracción independiente. Sin embargo, la recomendación de v5 va en la dirección opuesta: volver a unir queryKey y queryFn en una sola unidad. TkDodo llega a afirmar que «separar queryKey y queryFn fue un error». Al fin y al cabo, la clave es el conjunto de dependencias que utiliza la función, y ambas mantienen una relación inseparable.

Patrón práctico de composición con queryOptions

El verdadero potencial de queryOptions aparece al combinarla con una fábrica por dominio. La forma recomendada por la documentación oficial de v5 es la siguiente.

import { queryOptions } from '@tanstack/react-query';
 
export const todoQueries = {
  all: () => ['todos'] as const,
  lists: () => [...todoQueries.all(), 'list'] as const,
  list: (filters: TodoFilters) =>
    queryOptions({
      queryKey: [...todoQueries.lists(), filters],
      queryFn: () => fetchTodos(filters),
      staleTime: 30 * 1000,
    }),
  details: () => [...todoQueries.all(), 'detail'] as const,
  detail: (id: number) =>
    queryOptions({
      queryKey: [...todoQueries.details(), id],
      queryFn: () => fetchTodo(id),
      staleTime: 5 * 60 * 1000,
    }),
};

Veamos una por una las razones por las que este patrón resulta útil.

1. Permite obtener al mismo tiempo jerarquía e inferencia de tipos.

todoQueries.all() y todoQueries.lists() devuelven simples arreglos, mientras que todoQueries.detail(1) devuelve mediante queryOptions un objeto con una etiqueta de datos. Para invalidar se usa el arreglo; para invocar la consulta, el objeto de opciones.

useQuery(todoQueries.detail(1));                                // 옵션 객체
queryClient.invalidateQueries({ queryKey: todoQueries.all() }); // 배열

2. Los componentes pueden sobrescribir parcialmente las opciones.

Como el resultado de queryOptions sigue siendo un objeto, en el momento de la llamada pueden combinarse algunas opciones.

const { data: title } = useQuery({
  ...todoQueries.detail(1),
  select: (todo) => todo.title,  // 컴포넌트별로 다른 select 적용
});

Este patrón es especialmente potente porque el tipo devuelto por select se infiere automáticamente y el tipo de data se restringe a string. Desde el punto de vista del componente, es posible seleccionar solo la parte necesaria y mantener la definición del dominio intacta en un único lugar.

3. Los hooks personalizados que envuelven useQuery van desapareciendo.

Durante la época de v4, el patrón habitual consistía en crear hooks personalizados para cada dominio.

El problema era que, en cuanto se necesitaba una precarga, había que volver a escribir la misma definición. Como useTodoDetail no puede llamarse fuera de un componente, en el cargador del enrutador o en un manejador de eventos había que volver a escribir queryClient.prefetchQuery({ queryKey: [...], queryFn: ... }).

Con queryOptions, esa duplicación desaparece.

Una sola definición funciona en cualquier lugar. Por eso TkDodo recomienda «en v5, define queryOptions en lugar de crear hooks». Estos hooks quedan como una capa ligera que solo se añade cuando es necesaria, mientras que la definición del dominio puede existir de manera autosuficiente sin ellos.

Invalidación tras una mutación

El lugar en el que la jerarquía de queryKey brilla de verdad es la invalidación posterior a una mutación. Según la documentación de TanStack Query sobre invalidación de consultas, invalidateQueries utiliza de forma predeterminada la coincidencia por prefijo.

// 모든 todos 관련 쿼리 (list, detail, lists 모두)
queryClient.invalidateQueries({ queryKey: todoQueries.all() });
 
// 모든 list만 (detail은 건드리지 않음)
queryClient.invalidateQueries({ queryKey: todoQueries.lists() });
 
// 정확히 이 키만 (자식 키 매치 안 함)
queryClient.invalidateQueries({
  queryKey: todoQueries.detail(1).queryKey,
  exact: true,
});
 
// 더 복잡한 조건은 predicate으로
queryClient.invalidateQueries({
  predicate: (query) =>
    query.queryKey[0] === 'todos' &&
    (query.queryKey[2] as any)?.version >= 10,
});

Si las claves se diseñan de forma jerárquica, el alcance de la invalidación coincide con el significado del código. «Actualiza todas las tareas» se expresa con all(), «actualiza solo las listas» con lists() y «actualiza solo este elemento» con detail(id).

Si las claves estuvieran dispersas de forma plana, como ['todoList'] y ['todoDetail', 1], para invalidar «todo el dominio de tareas» habría que realizar dos llamadas separadas o crear y gestionar una constante de prefijo adicional. (Y, si al añadir una nueva clave al dominio se olvidase incorporarla a esa constante, se produciría un error que la dejaría fuera de la invalidación.)

Recuperar queryKey dentro de queryFn

Por último, hay otro patrón que merece atención. En realidad, queryFn recibe como argumento un objeto llamado QueryFunctionContext, que contiene la queryKey del momento de la llamada.

queryOptions({
  queryKey: ['user', userId, { include: 'profile' }] as const,
  queryFn: ({ queryKey }) => {
    const [, id, options] = queryKey;
    return fetchUser(id, options);
  },
});

¿Por qué resulta útil este patrón? Según Cómo aprovechar el contexto de la función de consulta, de TkDodo, permite forzar la sincronización entre las dependencias de queryKey y queryFn.

const sortBy = 'name';
 
queryOptions({
  queryKey: ['users'],
  queryFn: () => fetchUsers({ sortBy }),
});

Este código es peligroso porque queryFn depende de una variable externa. Además, aunque cambie sortBy, la caché no se actualiza porque esa dependencia no está incluida en la clave. Mientras queryFn tome variables de un cierre externo, siempre será posible cometer este error.

La solución es sencilla: hacer que queryFn no dependa de variables externas. Si todas las dependencias se extraen de queryKey, una variable que no figure en queryKey ni siquiera podrá utilizarse dentro de la función.

queryOptions({
  queryKey: ['users', { sortBy }] as const,
  queryFn: ({ queryKey: [, { sortBy }] }) => fetchUsers({ sortBy }),
});

Con esta estructura, cuando aparece una dependencia nueva no existe forma de usarla dentro de la función sin añadirla a queryKey. El compilador detectará que «esa clave no existe». La sincronización entre la clave y la función deja de depender de una convención y se delega al sistema de tipos.

Hasta dónde separar

Después de leer todo lo anterior puede surgir una pregunta: «Entonces, ¿hay que extraer todas las consultas a queryOptions?».

Mi respuesta, como casi siempre, es: «depende de la situación».

Conviene recordar que una abstracción no siempre es beneficiosa. Si una consulta solo se utiliza una vez, extraerla innecesariamente a una fábrica de dominio solo obliga a quien lee el código a desplazarse entre dos archivos. La evolución de los patrones de gestión de queryKey no significa «hay que usar siempre la herramienta más sofisticada», sino que «existe la posibilidad de subir un peldaño cuando resulte necesario».

Conclusión

En resumen, queryKey es la unidad fundamental con la que TanStack Query identifica y almacena en caché los datos asíncronos. En ese pequeño arreglo se concentran el identificador del espacio de caché, el arreglo de dependencias, el alcance de la invalidación y, desde v5, incluso la información sobre el tipo de los datos. Precisamente porque tantas responsabilidades convergen en un único punto, la forma de escribirlo y gestionarlo influye directamente en la carga cognitiva de toda la base de código.

Cada etapa fue la respuesta a un problema real que alguien encontró en su momento. Por eso, la conclusión no debe ser simplemente «como ahora estamos en v5, hay que usar exclusivamente queryOptions», sino «primero hay que identificar qué clase de problema está experimentando actualmente mi base de código». Introducir una fábrica de dominio en un proyecto donde bastan los arreglos en línea puede constituir por sí mismo un exceso de diseño.

Espero que quienes lean este artículo revisen también sus propios proyectos: cómo se distribuyen las queryKey por toda la base de código, cómo se realizan las invalidaciones y si esa estructura se ajusta al tamaño actual del equipo y a la complejidad del dominio.

Referencias

Durante mi experiencia profesional, muchas veces he sentido cierta incomodidad al escribir código para gestionar errores. Algunos se capturan con try/catch, otros con ErrorBoundary y otros mediante onError de TanStack Query. Además, sus ámbitos se solapan o divergen de formas sutiles. Por eso, a veces un error se escapa y otras se propaga hasta lugares donde no debería llegar.

El problema es que rara vez nos detenemos a ordenar de una vez cómo funcionan todas estas herramientas. Sabemos que «Error Boundary solo captura errores durante el renderizado», pero, si tuviéramos que explicar exactamente qué significa eso en la práctica, qué ocurre internamente al llamar a reset o en qué momento TanStack Query vuelve a lanzar un error cuando throwOnError está activado, probablemente no sabríamos responder.

Basándome en la guía oficial de React, la biblioteca react-error-boundary y la documentación oficial de TanStack Query v5, en este artículo explicaré hasta dónde llega la responsabilidad de cada herramienta de gestión de errores del frontend y cómo combinarlas.

Errores que React puede capturar y errores que no puede capturar

Empecemos por la pregunta más básica: ¿qué errores captura React?

La documentación oficial de React distingue claramente entre los errores que Error Boundary puede capturar y los que no.

Ámbito que captura Error Boundary

• Errores producidos durante el renderizado de componentes descendientes
• Errores producidos dentro de métodos del ciclo de vida
• Errores producidos en el constructor

Ámbito que Error Boundary no puede capturar

• Errores dentro de manejadores de eventos
• Errores de código asíncrono como setTimeout, requestAnimationFrame o Promise
• Errores durante el renderizado del lado del servidor (SSR)
• Errores producidos en el propio Error Boundary

¿Por qué es importante esta distinción? En realidad, la mayoría de los errores que tratamos habitualmente pertenecen a la segunda categoría. Por ejemplo, un servidor que devuelve un 500 tras ejecutar una mutación al pulsar un botón, una solicitud que falla dentro de useEffect o una lógica de validación que lanza una excepción al enviar un formulario. React no captura automáticamente estos errores. Debemos capturarlos y gestionarlos de forma explícita.

Por eso, la gestión de errores del frontend se divide en dos ramas: los errores de renderizado se tratan con Error Boundary y los demás, con try/catch o con manejadores proporcionados por bibliotecas. En el punto donde se cruzan ambas ramas, las bibliotecas de estado asíncrono como TanStack Query actúan como puente.

Qué es realmente un Error Boundary

Un Error Boundary no es más que un componente de clase con dos métodos del ciclo de vida. Según la documentación oficial de React, para convertirse en Error Boundary debe implementar uno de los dos métodos siguientes, aunque normalmente implementa ambos.

class ErrorBoundary extends React.Component {
  constructor(props) {
    super(props);
    this.state = { hasError: false };
  }
 
  // 에러 발생 시 state를 업데이트해 다음 렌더에서 fallback UI를 보여준다
  static getDerivedStateFromError(error) {
    return { hasError: true };
  }
 
  // 에러가 발생한 직후에 호출. 로깅 같은 사이드이펙트는 여기서 처리한다
  componentDidCatch(error, info) {
    logErrorToMyService(error, info.componentStack);
  }
 
  render() {
    if (this.state.hasError) {
      return this.props.fallback;
    }
    return this.props.children;
  }
}

getDerivedStateFromError debe ser una función pura. Su única función es devolver un nuevo estado, sin efectos secundarios. En cambio, componentDidCatch es el lugar destinado a esos efectos. Ahí se envía el error a Sentry o se imprime la pila de componentes en la consola.

Hay un detalle importante: estos dos métodos solo existen en los componentes de clase. Aún no hay una forma oficial de crear un Error Boundary con un componente funcional. La documentación oficial de React también lo indica expresamente.

Actualmente no existe ninguna forma de escribir un Error Boundary como componente funcional.

There is currently no way to write an Error Boundary as a function component.

Como resulta engorroso escribir un componente de clase cada vez, lo habitual es utilizar la biblioteca react-error-boundary. (La creó directamente Brian Vaughn, antiguo miembro del equipo de mantenimiento de React, y en la práctica se utiliza como un estándar.)

Las tres formas de definir la interfaz alternativa en react-error-boundary

La biblioteca react-error-boundary permite especificar la interfaz alternativa de su componente ErrorBoundary mediante propiedades de tres formas. Veamos brevemente cómo se utiliza cada una.

fallback

Es la forma más sencilla: se pasa JSX estático.

<ErrorBoundary fallback={<div>문제가 발생했습니다.</div>}>
  <Page />
</ErrorBoundary>

Se utiliza cuando no es necesario acceder al objeto de error ni a la función de restablecimiento. En la práctica, normalmente hace falta mostrar un mensaje o permitir un reintento, así que hasta ahora no he tenido ocasión de usarla en proyectos reales.

FallbackComponent

La interfaz alternativa se separa en otro componente y se pasa su referencia.

function ErrorFallback({ error, resetErrorBoundary }) {
  return (
    <div role="alert">
      <p>오류가 발생했습니다.</p>
      <pre>{error.message}</pre>
      <button onClick={resetErrorBoundary}>다시 시도</button>
    </div>
  );
}
 
<ErrorBoundary FallbackComponent={ErrorFallback}>
  <Page />
</ErrorBoundary>

El objeto de error y la función resetErrorBoundary se inyectan automáticamente como propiedades. Es una opción clara cuando la interfaz alternativa puede reutilizarse en otros lugares.

fallbackRender

Se utiliza cuando se quiere renderizar la interfaz alternativa en línea.

<ErrorBoundary
  fallbackRender={({ error, resetErrorBoundary }) => (
    <div role="alert">
      <p>오류가 발생했습니다: {error.message}</p>
      <button onClick={resetErrorBoundary}>다시 시도</button>
    </div>
  )}
>
  <Page />
</ErrorBoundary>

En esencia hace lo mismo que FallbackComponent, pero permite resolverlo en línea sin crear un componente separado. Es útil cuando se necesita acceder a un cierre léxico externo, como el estado o los manejadores del componente padre.

No existe una única opción correcta. El patrón que utilizo con frecuencia consiste en crear un componente ErrorFallback común e inyectarlo mediante FallbackComponent, porque el sistema de diseño y el tono deben mantenerse uniformes. Solo escribo un fallbackRender en línea cuando una página necesita una interfaz alternativa diferente.

¿Qué hace realmente el restablecimiento?

Al utilizar react-error-boundary, tarde o temprano aparece la función resetErrorBoundary: la que se ejecuta al pulsar el botón «Reintentar» de la interfaz alternativa. Veamos qué hace en realidad.

En pocas palabras, resetErrorBoundary solo indica al componente ErrorBoundary que reinicie su propio estado y vuelva a renderizar los elementos secundarios. No modifica automáticamente ningún estado externo, como la caché de TanStack Query.

Paso a paso, esto es lo que ocurre internamente:

1. Se llama a resetErrorBoundary().
2. El estado hasError interno de ErrorBoundary vuelve a false.
3. Opcionalmente, se ejecuta la función onReset. Aquí tienen lugar los efectos secundarios definidos por el usuario.
4. Se vuelven a renderizar los elementos secundarios. Si la causa del error, como el estado o la caché, sigue presente, se vuelve a lanzar el mismo error.

El cuarto punto es esencial. El restablecimiento solo significa «olvidemos el error e intentemos renderizar otra vez», no «corrijamos su causa». Por eso, limitarse a restablecer el estado puede provocar que el mismo error se repita indefinidamente.

Para resolver este problema existen dos herramientas adicionales.

onReset

Actúa como un punto de extensión que se ejecuta justo antes del restablecimiento. Aquí se limpia el estado externo que originó el error.

<ErrorBoundary
  FallbackComponent={ErrorFallback}
  onReset={() => {
    queryClient.invalidateQueries({ queryKey: ['user'] });
  }}
>
  <Page />
</ErrorBoundary>

resetKeys

Cuando cambia alguno de los valores de la lista, ErrorBoundary se restablece automáticamente. Se pasan claves para las que tenga sentido volver a intentarlo si cambian, como un parámetro de URL, un término de búsqueda o la pestaña seleccionada.

<ErrorBoundary
  FallbackComponent={ErrorFallback}
  resetKeys={[userId]}
>
  <UserProfile userId={userId} />
</ErrorBoundary>

Cuando cambia userId, se produce un restablecimiento automático y los elementos secundarios vuelven a renderizarse. Si el usuario accede a otro perfil, el error anterior desaparece de forma natural.

¿Cómo se capturan los errores de manejadores de eventos y del código asíncrono?

Ya hemos visto que Error Boundary no puede capturar errores de manejadores de eventos ni de código asíncrono. Sin embargo, la mayoría de los errores con los que trabajamos nacen ahí. ¿Qué podemos hacer?

Para resolverlo, react-error-boundary ofrece el hook useErrorBoundary. Este devuelve una función llamada showBoundary; al invocarla, se puede enviar el error de forma explícita al ErrorBoundary más cercano.

import { useErrorBoundary } from 'react-error-boundary';
 
function MyComponent() {
  const { showBoundary } = useErrorBoundary();
 
  const handleClick = async () => {
    try {
      await someAsyncOperation();
    } catch (error) {
      showBoundary(error);
    }
  };
 
  return <button onClick={handleClick}>실행</button>;
}

La clave es que el desarrollador debe elevar el error explícitamente. React no lo hace por sí solo. Para trasladar un error asíncrono al ámbito de ErrorBoundary hay que capturarlo con try/catch y pasarlo a showBoundary.

Con este patrón, la pregunta «¿por qué ErrorBoundary captura unos errores y no otros?» queda resuelta con claridad. La respuesta es sencilla: «¿se elevó hasta la fase de renderizado o no?».

¿Cómo gestiona los errores TanStack Query?

Después de ordenar todo lo anterior surge una pregunta natural. useQuery, que usamos a diario, trabaja con solicitudes asíncronas; ¿cómo se gestionan los errores que se producen en ellas?

De forma predeterminada, TanStack Query expone el error en el campo error.

const { data, error, isError } = useQuery({
  queryKey: ['todos'],
  queryFn: fetchTodos,
});
 
if (isError) {
  return <div>에러: {error.message}</div>;
}

Esta es la forma más sencilla. Aunque se produzca un error, el componente sigue renderizándose normalmente y el valor simplemente queda almacenado en el campo error. ErrorBoundary no interviene.

Conviene subrayar un dato importante: el comportamiento predeterminado de TanStack Query es «no lanzar el error». Tanto si queryFn lanza una excepción como si devuelve un rechazo, el error solo entra en el campo error y no interrumpe el flujo de renderizado de React. Por eso, sin una configuración adicional, ErrorBoundary nunca se activa.

Además, TanStack Query reintenta automáticamente los errores tres veces de forma predeterminada.

El retryDelay predeterminado utiliza una espera exponencial y aumenta hasta un máximo de 30 segundos. Esto significa que el usuario no ve el error inmediatamente después del primer fallo. Se reintenta tras intervalos de 1, 2 y 4 segundos y, si aun así falla, se rellena el campo error. (Si alguna vez durante el desarrollo se ha preguntado «¿por qué tarda tanto en aparecer el error?», casi con total seguridad esta es la causa.)

Conectar ErrorBoundary mediante throwOnError

Entonces, ¿cómo se envían los errores de TanStack Query a ErrorBoundary? La respuesta es la opción throwOnError. (Hasta v4 se llamaba useErrorBoundary, pero en v5 pasó a llamarse throwOnError.)

const { data } = useQuery({
  queryKey: ['todos'],
  queryFn: fetchTodos,
  throwOnError: true,
});

Cuando esta opción está activada, TanStack Query vuelve a lanzar el error en el siguiente ciclo de renderizado. Así, ese lanzamiento se convierte en un error de la fase de renderizado y ErrorBoundary por fin puede capturarlo.

throwOnError también acepta una función. De este modo se puede decidir qué errores se envían a ErrorBoundary y cuáles gestiona directamente el componente.

useQuery({
  queryKey: ['todos'],
  queryFn: fetchTodos,
  // 5xx 서버 에러만 ErrorBoundary로 보낸다
  throwOnError: (error) => error.response?.status >= 500,
});

Este patrón resulta práctico porque, normalmente, lo natural es mostrar en el lugar correspondiente los errores del cliente como los 4xx, por ejemplo un fallo de validación o falta de permisos, mientras que para errores del servidor como los 5xx conviene cubrir toda la página y mostrar un mensaje como «Vuelva a intentarlo dentro de unos instantes».

useSuspenseQuery

Si se utiliza useSuspenseQuery, no hace falta preocuparse por throwOnError. En modo Suspense, el comportamiento predeterminado es lanzar siempre los errores.

Es decir, utilizar useSuspenseQuery implica que Suspense gestiona la carga y ErrorBoundary gestiona los errores. Ya no hacen falta condicionales como if (isError) o if (isLoading) dentro del componente; en su lugar, hay que envolverlo externamente con ambos límites.

QueryErrorResetBoundary

Llegados a este punto surge otra pregunta: ¿qué ocurre cuando el usuario pulsa el botón «Reintentar» de la interfaz alternativa?

Como vimos antes, resetErrorBoundary solo reinicia el estado hasError de ErrorBoundary. Sin embargo, en la caché de TanStack Query sigue existiendo una consulta bloqueada en estado de error. Cuando los elementos secundarios vuelven a renderizarse, TanStack Query consulta la caché, determina que la consulta ya tiene un error y vuelve a lanzar inmediatamente el mismo error. (Es un bucle infinito infernal.)

Para resolver este problema, TanStack Query ofrece el hook useQueryErrorResetBoundary y el componente QueryErrorResetBoundary. Sus nombres son largos, pero su función es sencilla: emitir la orden «restablece el estado de error de las consultas de este ámbito».

import { useQueryErrorResetBoundary } from '@tanstack/react-query';
import { ErrorBoundary } from 'react-error-boundary';
 
function App() {
  const { reset } = useQueryErrorResetBoundary();
 
  return (
    <ErrorBoundary
      onReset={reset}
      fallbackRender={({ resetErrorBoundary }) => (
        <div>
          <p>에러가 발생했습니다.</p>
          <button onClick={resetErrorBoundary}>다시 시도</button>
        </div>
      )}
    >
      <Page />
    </ErrorBoundary>
  );
}

Veamos en orden cronológico lo que ocurre aquí.

1. El usuario pulsa el botón «Reintentar» → se llama a resetErrorBoundary()
2. ErrorBoundary ejecuta la función onReset → se llama a reset() (se reinicia el estado de error de TanStack Query)
3. ErrorBoundary reinicia su propio estado y vuelve a renderizar los elementos secundarios
4. Se ejecuta el useQuery de los elementos secundarios → como el estado de error ha desaparecido, vuelve a intentar la obtención de datos

La clave está en conectar onReset con reset. Gracias a esa línea, ErrorBoundary y TanStack Query sincronizan sus estados.

Uso como componente

También se puede conseguir lo mismo con un componente en lugar de usar la función anterior. Basta con elegir una de las dos alternativas.

import { QueryErrorResetBoundary } from '@tanstack/react-query';
import { ErrorBoundary } from 'react-error-boundary';
 
function App() {
  return (
    <QueryErrorResetBoundary>
      {({ reset }) => (
        <ErrorBoundary
          onReset={reset}
          fallbackRender={({ error, resetErrorBoundary }) => (
            <div role="alert">
              <p>에러가 발생했습니다: {error.message}</p>
              <button onClick={resetErrorBoundary}>다시 시도</button>
            </div>
          )}
        >
          <Page />
        </ErrorBoundary>
      )}
    </QueryErrorResetBoundary>
  );
}

La principal diferencia con la versión basada en un hook es que pasa la función reset a sus elementos secundarios mediante el patrón de propiedad de renderizado. QueryErrorResetBoundary recibe una función como elemento secundario, le pasa { reset } como argumento y renderiza su valor de retorno. Por eso puede conectarse inmediatamente mediante onReset={reset}.

Si no existe un QueryErrorResetBoundary cercano, la versión basada en un hook restablece los errores de la caché global. La versión basada en un componente limita el alcance del restablecimiento a su propio árbol de descendientes. Si se quiere controlar el ámbito de forma más precisa, la versión de componente es más segura.

Conviene aclarar un punto: el restablecimiento no borra la caché. No elimina todos los datos, sino que libera el estado de las consultas marcadas con error. Si se quieren invalidar realmente los datos, hay que llamar por separado a queryClient.invalidateQueries().

Errores de mutaciones

Hasta ahora, casi todos los patrones se han explicado desde la perspectiva de useQuery. Sin embargo, el caso de useMutation es algo diferente.

La mayor diferencia es que una mutación suele comenzar a raíz de una acción explícita del usuario, como un clic o un envío. Por eso, resulta natural gestionar el error cerca de esa acción. En vez de cubrir toda la página con una interfaz alternativa, es preferible mostrar en una notificación o junto al formulario un texto como «Pago fallido: compruebe de nuevo los datos de su tarjeta».

En Dominar las mutaciones en React Query, TkDodo resume la esencia de esta diferencia en una frase: las consultas son declarativas y las mutaciones son imperativas. Una consulta se ejecuta automáticamente al montar el componente, puede ser observada por otros componentes con la misma clave y queda almacenada en caché para reutilizarse. En cambio, una mutación no se ejecuta hasta que el usuario pulsa un botón, no se almacena en caché y queda vinculada de forma individual a la instancia del componente que la invocó. Esta diferencia esencial separa también sus formas de gestionar errores.

En useQuery, el valor predeterminado de retry es 3, pero en useMutation, el valor predeterminado de retry es 0. La razón es sencilla: una mutación produce efectos secundarios. Si una solicitud de pago falla por agotarse el tiempo de espera de la red y la biblioteca la repite automáticamente dos veces más, la tarjeta del usuario podría recibir tres cargos.

Por eso, la regla es activar explícitamente los reintentos de una mutación solo cuando el desarrollador pueda garantizar que la operación es idempotente. Esto se limita a consultas seguras del tipo GET cuyo resultado esté garantizado aunque se envíe dos veces la misma solicitud, o a casos en los que el servidor impida duplicados mediante una clave de idempotencia.

Los errores de useQuery quedan fijados en la caché. Por eso se propagan inmediatamente a otros componentes que observan la misma queryKey y hay que restablecerlos en conjunto mediante mecanismos como QueryErrorResetBoundary.

Las mutaciones son diferentes. El error de una mutación que falla en un componente solo permanece en el estado de esa instancia. No afecta a las mutaciones de otros componentes que utilicen la misma mutationFn. Por eso TanStack Query no tiene nada parecido a MutationErrorResetBoundary: no es necesario.

Esta diferencia tiene una consecuencia práctica. Si dos componentes invocan useMutation por separado, el error producido en uno no es visible en el otro. Si se necesita conocer «el error de esta mutación en toda la aplicación», su onError a nivel de componente no basta; hay que elevarlo a MutationCache.onError.

mutate vs mutateAsync

useMutation devuelve dos funciones de ejecución. La diferencia entre ellas determina cómo se gestionan los errores.

El tipo de retorno de mutate es void. No devuelve una Promise. Por tanto, no es posible esperar el resultado con await y este solo puede recibirse mediante manejadores como onSuccess/onError.

const mutation = useMutation({
  mutationFn: createPost,
  onError: (error) => {
    toast.error(`등록 실패: ${error.message}`);
  },
});
 
mutation.mutate(newPost);

En cambio, mutateAsync devuelve una Promise. El error se puede gestionar con try/catch.

const mutation = useMutation({ mutationFn: createPost });
 
const handleSubmit = async () => {
  try {
    const result = await mutation.mutateAsync(newPost);
    router.push(`/posts/${result.id}`);
  } catch (error) {
    // 여기서 처리
  }
};

¿Cuándo conviene usar cada una? Yo aplico los siguientes criterios.

• Se necesita una acción posterior al terminar la mutación, por ejemplo navegar al finalizar o utilizar el resultado → mutateAsync
• Solo hay que ejecutarla y delegar los efectos secundarios en los manejadores configurados, por ejemplo alternar un «Me gusta» o mostrar únicamente una notificación → mutate + onError

Hay un error frecuente que conviene señalar: usar mutateAsync sin try/catch provoca el rechazo no gestionado de una promesa. mutate, que gestiona el error mediante los manejadores configurados, lo absorbe, mientras que el comportamiento predeterminado de mutateAsync consiste en lanzarlo al código que la invoca. Si se mezclan sin conocer esta diferencia, la consola se llena de advertencias rojas.

onError

Hay otro detalle que suele pasarse por alto. En useMutation, onError puede definirse en dos lugares, en el hook y en mutate.

const mutation = useMutation({
  mutationFn: createPost,
  onError: (error) => {
    Sentry.captureException(error);
  },
});

En el nivel del hook se ejecuta siempre, mientras que en el nivel de mutate solo se ejecuta al invocarla.

mutation.mutate(newPost, {
  onError: (error) => {
    setFormError(error.message);
  },
});

La documentación oficial especifica este orden de ejecución: nivel del hook → nivel de mutate. Si ambos manejadores están definidos, se ejecuta primero el del hook y después el de mutate.

Gestión global de errores

Todos los patrones vistos hasta ahora operan a nivel de componente. Sin embargo, puede haber requisitos como «registrar todos los errores de las consultas en un solo lugar» o «cerrar siempre la sesión ante un error 401». Para estas preocupaciones transversales se pueden añadir manejadores a QueryCache/MutationCache al crear el QueryClient.

import { QueryClient, QueryCache, MutationCache } from '@tanstack/react-query';
 
const queryClient = new QueryClient({
  queryCache: new QueryCache({
    onError: (error, query) => {
      if (query.state.data !== undefined) {
        toast.error(`데이터 갱신 실패: ${error.message}`);
      }
    },
  }),
  mutationCache: new MutationCache({
    onError: (error) => {
      if (error.status === 401) {
        redirectToLogin();
      }
    },
  }),
});

La clave es que QueryCache.onError se invoca una sola vez por cada consulta. Aunque varios componentes observen la misma consulta, la función solo se ejecuta una vez, por lo que no se producen problemas como notificaciones duplicadas.

También se puede comprobar query.state.data !== undefined, como en el ejemplo anterior. Si falla una actualización cuando ya hay datos en caché, el usuario sigue viendo información en pantalla. Cubrir la página con un ErrorBoundary sería excesivo; basta con informarle del fallo. En cambio, si falla la carga inicial y no hay datos almacenados, lo apropiado es que ErrorBoundary capture el error y muestre la interfaz alternativa.

Al combinar ambos flujos se puede diseñar una política clara: «ErrorBoundary para los fallos de carga inicial y una notificación para los fallos de actualización en segundo plano».

Componente común

Llegados aquí, es natural pensar: si resulta molesto envolver todo cada vez con tres capas de QueryErrorResetBoundary, ErrorBoundary y Suspense, ¿por qué no agruparlas en un componente reutilizable?

Es una idea razonable. De hecho, hace tiempo también creé y utilicé un componente AsyncBoundary como el siguiente.

import { QueryErrorResetBoundary } from '@tanstack/react-query';
import { Suspense, type ComponentType, type ReactNode } from 'react';
import { ErrorBoundary, type FallbackProps } from 'react-error-boundary';
import { ErrorFallback } from './ErrorFallback';
import { Spinner } from './Spinner';
 
interface Props {
  children: ReactNode;
  pendingFallback?: ReactNode;
  rejectedFallback?: ComponentType<FallbackProps>;
}
 
export function AsyncBoundary({
  children,
  pendingFallback = <Spinner />,
  rejectedFallback = ErrorFallback,
}: Props) {
  return (
    <QueryErrorResetBoundary>
      {({ reset }) => (
        <ErrorBoundary onReset={reset} FallbackComponent={rejectedFallback}>
          <Suspense fallback={pendingFallback}>{children}</Suspense>
        </ErrorBoundary>
      )}
    </QueryErrorResetBoundary>
  );
}