Cómo estructuro una aplicación React grande

Muchas aplicaciones React comienzan con una estructura como esta:

src/
|-- components/
|-- hooks/
|-- services/
|-- types/
|-- utils/
`-- pages/

Parece organizada porque cada archivo tiene una categoría técnica. El problema es que esas categorías no dicen nada sobre la responsabilidad dentro del producto.

Una tabla de historial de pedidos, un diálogo de checkout y la navegación principal son componentes. Un formateador de moneda, una comprobación de permisos y un cálculo del checkout pueden llamarse utilidades. Un hook de obtención de datos y otro de atajos de teclado son hooks, aunque pertenezcan a partes totalmente distintas del producto.

A medida que la aplicación crece, estas carpetas desarrollan fallos previsibles:

• Los desarrolladores deben buscar en varios directorios globales para entender una funcionalidad.
• Se acumulan nombres similares porque la carpeta ya no aporta contexto de negocio.
• Los detalles privados de implementación se convierten en importaciones cómodas para funcionalidades no relacionadas.
• Cambios que deberían ser locales exigen editar componentes, hooks, servicios, tipos y utilidades.
• Nadie sabe qué es realmente compartido y qué simplemente acabó en una ubicación compartida.
• Aparecen dependencias circulares porque no existe una dirección de recorrido declarada.

El problema no son las palabras components, hooks o utils. Sigo usando esas carpetas dentro de un módulo delimitado. El problema es convertir el tipo técnico en el principio de organización de más alto nivel.

A nivel de aplicación, organizo por responsabilidad y motivo de cambio.

Una funcionalidad es un comportamiento que puede realizar un usuario u otro sistema: cancelar un pedido, invitar a un miembro, actualizar un método de pago o exportar un informe. Prefiero nombres de capacidades a áreas vagas como dashboard o common.

Un módulo de funcionalidad puede contener:

• Los componentes React utilizados para realizar esa capacidad.
• Hooks específicos y estado de interacción.
• Validación y mapeo de formularios.
• Operaciones de API utilizadas solo por la funcionalidad.
• Coordinación entre reglas de dominio e infraestructura.
• Pruebas que protegen el comportamiento de la funcionalidad.

Esto mantiene juntos los archivos que cambian juntos. Un desarrollador que trabaja en la cancelación de pedidos no debería visitar seis carpetas globales para seguir una interacción.

Organizar por funcionalidades no significa poner todo lo relacionado con pedidos en una enorme carpeta orders. Un dominio es un concepto de negocio. Una funcionalidad es una operación que involucra ese concepto. Esa distinción evita que un gran módulo de dominio se convierta en el siguiente cajón de sastre.

La capa de ruta o aplicación compone las funcionalidades. Una funcionalidad no debe entrar en los archivos internos de otra para tomar prestado un hook o componente. Si dos funcionalidades necesitan la misma regla de negocio, probablemente pertenezca a un módulo de dominio. Si necesitan el mismo elemento técnico, probablemente pertenezca a shared.

Separo la mecánica de transporte de las operaciones del producto.

La capa compartida de API puede asumir cuestiones como URL base, cabeceras de autenticación, cancelación de solicitudes, normalización de errores, cabeceras de trazas y análisis de JSON. No debe saber cómo cancelar un pedido ni invitar a un miembro.

El adaptador del dominio o funcionalidad correspondiente contiene las rutas de endpoints, los DTO de solicitud y respuesta y el mapeo entre datos de transporte y tipos de aplicación.

import { httpClient } from "@/shared/api";

type CancelOrderResponseDto = {
  order_id: string;
  status: "cancelled";
  cancelled_at: string;
};

export async function cancelOrder(orderId: string) {
  const response = await httpClient.post<CancelOrderResponseDto>(
    `/orders/${orderId}/cancellation`,
  );

  return {
    orderId: response.order_id,
    status: response.status,
    cancelledAt: new Date(response.cancelled_at),
  };
}

Este límite evita que los formatos de transporte se filtren a los componentes y a las reglas de dominio. Si el backend cambia el nombre de un campo o devuelve otra representación, el cambio se absorbe donde el contrato externo entra en el módulo.

Evito un único api.ts o services.ts global que contenga todos los endpoints. Esos archivos centralizan volatilidad no relacionada. Parecen cómodos hasta que cada equipo debe editar el mismo módulo y todos los consumidores pueden importar cada operación.

El modelo de dependencias es deliberadamente sencillo:

app  ----> features ----> domains
 |           |              |
 +-----------+--------------> shared

• App puede componer funcionalidades, dominios y elementos compartidos.
• Las funcionalidades pueden depender de módulos de dominio e infraestructura compartida.
• Los dominios pueden depender de elementos compartidos pequeños y estables, pero no de funcionalidades ni de app.
• Shared no debe depender de funcionalidades o dominios del producto.
• Una funcionalidad no debe importar la implementación privada de otra.

Cuando dos funcionalidades necesitan coordinarse, las compongo en la capa de aplicación o extraigo el comportamiento estable de negocio que comparten. No resuelvo el problema con una importación relativa profunda.

Estas reglas deben poder aplicarse. Los alias de ruta mejoran la legibilidad, pero no crean límites. En un equipo grande, añado reglas de lint para importaciones restringidas, herramientas de límites de módulos o exports de paquetes para que una importación no válida falle antes de la revisión. En un monorepo, las mismas reglas pueden expresarse como dependencias entre paquetes.

Existen excepciones legítimas. Una regla de límites debe hacer visible un acoplamiento inusual, no forzar soluciones rebuscadas. Cuando permito una excepción, registro por qué existe la dependencia, quién la asume y qué permitiría eliminarla más adelante.

Organizo las pruebas por responsabilidad, no por el vocabulario de la biblioteca de pruebas.

src/
|-- domains/orders/tests/
|   `-- can-cancel-order.test.ts
|-- features/cancel-order/tests/
|   |-- cancel-order-contract.test.ts
|   `-- cancel-order-dialog.test.tsx
`-- shared/testing/
    |-- render-application.tsx
    |-- factories/
    `-- server/

e2e/
`-- cancel-order.spec.ts

Las pruebas puras de dominio viven con el dominio. Las pruebas de comportamiento y contrato de una funcionalidad viven con ella. Shared testing contiene infraestructura utilizada por muchos módulos: envoltorios de renderizado, factorías, constructores deterministas y manejadores de red. No debe convertirse en una segunda carpeta utils llena de fixtures específicos de negocio.

Las pruebas de extremo a extremo viven en la raíz del repositorio porque ejercitan recorridos desplegados de usuario que atraviesan límites de módulos. Su carpeta refleja el alcance de la prueba, no la preferencia por una herramienta concreta.

Un árbol de nivel superior dividido en pruebas unitarias, de integración y de componentes suele recrear el mismo problema de navegación que components, hooks y utils. Esas etiquetas describen cómo se ejecuta una prueba. No indican quién asume el comportamiento cuando falla.

No detendría la entrega para reorganizar una aplicación existente según este árbol. Las grandes reestructuraciones crean agitación sin demostrar que los límites nuevos sean mejores.

En su lugar, elijo un corte vertical relevante. Coloco su UI, lógica de interacción, adaptador de API y reglas de dominio detrás de una API de funcionalidad. Corrijo la dirección de dependencias alrededor de ese corte y utilizo la siguiente funcionalidad para comprobar si el patrón sigue funcionando.

La estructura se gana su lugar cuando los cambios rutinarios se vuelven más locales, el código privado permanece privado y los desarrolladores pueden explicar por qué se permite una dependencia. Si un límite lucha repetidamente contra el producto, cambio el límite. La coherencia es valiosa, pero proteger una abstracción equivocada no lo es.