Arquitectura (Feature-Sliced Design)
Prioridad: P2 (MEDIO)
Adopta Feature-Sliced Design (FSD) para aplicaciones escalables. Advertencia: FSD introduce mucho código repetitivo. Úsalo solo si se espera que el proyecto crezca significativamente (p. ej., 20+ features). Para proyectos más pequeños, se prefiere una estructura simple basada en módulos.
Estrategia
- Límites RSC: Aplica reglas estrictas de serialización para las props que se pasan del Servidor al Cliente. Consulta Límites RSC y Serialización.
- Capa App Delgada: El directorio
app/(App Router) es solo para enrutamiento.- Regla:
page.tsxsolo debe importar Widgets/Features. Sin lógica de negocio (useEffect,fetch) directamente en las páginas.
- Regla:
- Slices sobre Tipos: Agrupa código por Dominio de Negocio (Usuario, Producto, Carrito), no por Tipo de Archivo (Componentes, Hooks, Utilidades).
- Mal:
src/components/LoginForm.tsx,src/hooks/useLogin.ts - Bien:
src/features/auth/login/que contiene ambos.
- Mal:
- Jerarquía de Capas: El código solo puede importar desde capas inferiores.
App->Widgets->Features->Entities->Shared.
- Evita Entidades Excesivas: No crees Entidades de forma preventiva.
- Regla: Inicia la lógica en
FeaturesoPages. Muévela aEntitiessolo cuando los datos/lógica se reutilicen estrictamente en varias features diferentes. - Regla: El CRUD simple pertenece a
shared/api, no aentities.
- Regla: Inicia la lógica en
- Segmentos Estándar: Usa nombres de segmento estándar dentro de los slices.
ui(Componentes),model(Estado/acciones),api(Obtención de datos),lib(Ayudantes),config(Constantes).- Evita:
components,hooks,servicescomo nombres de segmento.
Referencia de Estructura
Para la disposición específica de directorios y las definiciones de capas, consulta la documentación de referencia.
- Estructura de Carpetas FSD
- Empaquetado y Compatibilidad
- Selección en Tiempo de Ejecución (Edge/Node)
- Trucos de Depuración y MCP
Lista de Verificación de Arquitectura (Obligatoria)
-
Importaciones entre Capas: ¿Alguna capa importa desde una capa SUPERIOR? (App > Widgets > Features > Entities > Shared)
-
Lógica de Página: ¿
page.tsxes delgada, contiene solo Widgets/Features y cerouseEffect/fetch? -
Límites RSC: ¿Los Componentes Servidor están aislados de los Componentes Cliente con los límites 'use client' adecuados?
-
API Pública: ¿Todo acceso a un slice se realiza a través del
index.tsde nivel superior (API pública)? -
Entre Slices: ¿Los slices dentro de la misma capa (p. ej., dos features) importan directamente entre sí? (Prohibido)
-
Acciones del Servidor: Colócalas en la carpeta
model/de una Feature (p. ej.,features/auth/model/actions.ts). -
Acceso a Datos (DAL): Coloca la lógica en la carpeta
model/de una Entity (p. ej.,entities/user/model/dal.ts). -
Componentes UI: La UI base (shadcn) pertenece a
shared/ui. La UI específica de una feature pertenece afeatures/*/ui.
Antipatrones
- Sin importaciones entre slices: Los slices en la misma capa no deben importarse directamente entre sí.
- Sin lógica de negocio en
page.tsx: Las páginas importan solo Widgets/Features; cerouseEffect/fetch. - Sin carpetas por tipo de archivo: Agrupa por dominio (
features/auth/), no por tipo (components/,hooks/). - Sin creación prematura de Entities: Comienza en Features; muévelas a Entities solo si hay reutilización estricta.