La estructura que tu proyecto necesita para crecer sin caos

Mantener un proyecto frontend organizado cuando empieza a crecer es un desafío real. ¿Dónde pones el componente del formulario de comentarios? ¿Y la lógica para buscar posts? Si todo va a carpetas genéricas como components o utils, al final se convierte en un cajón de sastre donde nada es fácil de encontrar.

La estructura que a mí me ha funcionado sigue un principio conocido como Screaming Architecture (Arquitectura que Grita). La idea es que la estructura de carpetas debería “gritarte” de qué trata la aplicación con solo mirarla. En la práctica, esto se traduce en dividir todo en dos carpetas principales: features y shared.

La estructura: features y shared

La idea central es agrupar el código por lo que la aplicación hace, no por el tipo de archivo que es. Así es como se ve:

1
/src
2
  /features
3
    /blog
4
      /components
5
        PostList.tsx
6
        PostCard.tsx
7
      /hooks
8
        usePosts.ts
9
      /utils
10
        formatPostDate.ts
11
    /comments
12
      /components
13
        CommentForm.tsx
14
      /api
15
        createComment.ts
16
  /shared
17
    /components
18
      Button.tsx
19
      Modal.tsx
20
    /utils
21
      formatDate.ts
22
      apiClient.ts
23
    /hooks
24
      useLocalStorage.ts

1. /features (Características) Aquí vive cada una de las funcionalidades principales de tu app. Cada feature (como blog o comments) tiene su propia carpeta y dentro puede tener su propia estructura (componentes, hooks, lógica de API). Esto hace que todo lo relacionado con una función esté junto, sea fácil de encontrar y se pueda modificar o incluso eliminar con mínimo impacto en otras partes.

2. /shared (Compartido) Aquí va todo lo que es transversal y se usa en múltiples features. Un botón genérico, un cliente configurado para la API, un hook para el localStorage o un formateador de fechas. Dentro de shared sí tiene sentido organizar por tipo de archivo (components, utils, hooks), porque su propósito es ser una librería interna de recursos técnicos reutilizables.

¿Por qué merece la pena?

• Escalabilidad natural: Añadir una nueva función como user-profile es tan simple como crear una nueva carpeta dentro de features. El proyecto crece de forma ordenada.
• Mantenibilidad: Si necesitas cambiar algo de los comentarios, sabes que todo está en /features/comments. No tienes que buscar entre decenas de archivos en una carpeta components gigante.
• Claridad para el equipo: Cualquier persona nueva en el proyecto puede abrir la carpeta features y entender de un vistazo las capacidades de la aplicación.

Para un proyecto pequeño o un prototipo, puede parecer excesivo. Pero en el momento en que la aplicación gana complejidad, esta separación entre lógica de negocio por función y utilidades técnicas globales se vuelve una de las mejores decisiones que puedes tomar para la salud a largo plazo de tu código.