0Pricing
Frontend Academy · Lección

Estructura de carpetas basada en funcionalidades

Organice el código por dominio funcional en lugar de por tipo, mantenga juntos tests, estilos y componentes y establezca límites con eslint-plugin-boundaries.

Estructura de carpetas basada en funcionalidades es una lección gratuita de Frontend Academy en CoddyKit. Esta es la lección 4 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de Frontend Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de Frontend Academy incluye 4 lecciones en total.

Dos formas de organizar el código

Puede agrupar el código por tipo (components/, hooks/, services/, types/) o por funcionalidad (auth/, checkout/, dashboard/, cada una con sus propios components, hooks, etc.). La organización por funcionalidades es más adecuada para aplicaciones medianas y grandes.

Organización por tipo: la trampa predeterminada

La estructura clásica de los tutoriales de React agrupa todo por tipo. Escala mal: cada cambio de archivo afecta a varias carpetas no relacionadas, y «encontrar todo el código de checkout» implica buscar con grep en todo el árbol.

// Type-based (avoid for large apps):
src/
  components/
    Button.tsx
    LoginForm.tsx
    CartItem.tsx
  hooks/
    useAuth.ts
    useCart.ts
  services/
    auth.ts
    cart.ts
  types/
    User.ts
    CartItem.ts

Estructura basada en funcionalidades

Agrupe en una sola carpeta todo lo relacionado con una funcionalidad. Es fácil de encontrar, fácil de eliminar y fácil de comprender.

src/
  features/
    auth/
      LoginForm.tsx
      SignupForm.tsx
      useAuth.ts
      auth.service.ts
      auth.types.ts
      auth.test.tsx
    cart/
      CartItem.tsx
      CartSummary.tsx
      useCart.ts
      cart.service.ts
      cart.types.ts
  shared/
    components/
      Button.tsx
    hooks/
      useDebounce.ts

Agrupación dentro de una funcionalidad

Una carpeta de funcionalidad contiene components, hooks, services, types y tests: todo el código necesario para ese dominio. ¿Un desarrollador nuevo quiere entender auth? Abra auth/. ¿Quiere eliminar auth? Elimine la carpeta.

Código compartido frente a código de funcionalidades

El código utilizado por 2 o más funcionalidades pasa a shared/ (o lib/). El código utilizado por una sola funcionalidad permanece dentro de ella. Resista la tentación de pensar «quizá sea reutilizable más adelante»: espere al segundo uso antes de extraerlo.

Reglas de límites entre funcionalidades

Las funcionalidades no deberían importarse directamente entre sí. Si dos funcionalidades necesitan compartir código, esa parte pasa a shared/. Si necesitan coordinarse, use eventos o un almacén compartido en el nivel de la aplicación.

Aplicar límites con ESLint

Use eslint-plugin-boundaries o eslint-plugin-import para exigir que las funcionalidades puedan importar desde shared, pero no entre sí.

// .eslintrc.json
{
  "plugins": ["boundaries"],
  "settings": {
    "boundaries/elements": [
      { "type": "feature", "pattern": "src/features/*" },
      { "type": "shared",  "pattern": "src/shared/*" }
    ]
  },
  "rules": {
    "boundaries/element-types": ["error", {
      "default": "disallow",
      "rules": [
        { "from": "feature", "allow": ["shared"] },
        { "from": "shared",  "allow": ["shared"] }
      ]
    }]
  }
}

API pública por funcionalidad

Cada funcionalidad exporta una API pública mediante features/auth/index.ts. El resto del código importa desde '@/features/auth', no desde rutas internas. Así puede refactorizar los elementos internos sin romper a los consumidores.

// features/auth/index.ts
export { LoginForm } from './LoginForm';
export { useAuth } from './useAuth';
export type { User, AuthState } from './auth.types';

// Consumers:
import { LoginForm, useAuth } from '@/features/auth';
// NOT: import { LoginForm } from '@/features/auth/LoginForm';

Anidar subfuncionalidades

Las funcionalidades grandes pueden tener subcarpetas: dashboard/widgets/, dashboard/charts/. Evite anidar a más de 2 o 3 niveles: buscar se vuelve complicado.

Dónde colocar las rutas

Las páginas y rutas pueden estar en una carpeta de nivel superior pages/ o routes/. Son delgadas: obtienen componentes y hooks de las funcionalidades y los combinan.

src/
  pages/
    Dashboard.page.tsx   // composes Dashboard widgets from features/dashboard/
    Cart.page.tsx        // composes from features/cart/
  features/
  shared/

Migrar una aplicación existente

Empiece solo con las funcionalidades nuevas: coloque el código nuevo en features/. No refactorice todo de una vez. A medida que modifique archivos antiguos, trasládelos gradualmente. Las reglas de límites de ESLint evitan regresiones en la nueva estructura.

Cuándo sigue funcionando la organización por tipo

En aplicaciones muy pequeñas (con menos de 30 componentes) o en bibliotecas, la organización por tipo funciona bien. Use la organización por funcionalidades en cuanto tenga dominios de negocio diferenciados (auth, checkout, billing, settings).

Comprobación rápida

¿Cuál es la principal ventaja organizativa de agrupar el código por funcionalidad en lugar de por tipo de archivo?

Repaso: estructura basada en funcionalidades

features/ contiene código específico de cada dominio; shared/ contiene utilidades compartidas entre funcionalidades. Cada funcionalidad exporta un index.ts público. Las funcionalidades no se importan entre sí: solo importan desde shared. Aplique las reglas con eslint-plugin-boundaries. Las páginas y rutas combinan las funcionalidades. Migre de forma gradual. La organización por tipo funciona bien en aplicaciones pequeñas.

Preguntas frecuentes

¿La lección «Estructura de carpetas basada en funcionalidades» es gratis?

Sí — el texto completo de «Estructura de carpetas basada en funcionalidades» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de Frontend Academy, actualiza a CoddyKit PRO. El curso de Frontend Academy incluye 4 lecciones en total.

¿Qué aprenderé en «Estructura de carpetas basada en funcionalidades»?

Organice el código por dominio funcional en lugar de por tipo, mantenga juntos tests, estilos y componentes y establezca límites con eslint-plugin-boundaries. Practicas Frontend Academy con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.

¿Necesito experiencia previa para empezar Frontend Academy?

No se requiere experiencia previa. Frontend Academy en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 4 de 4.

¿Cuánto tiempo toma la lección «Estructura de carpetas basada en funcionalidades»?

La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.

¿Puedo escribir y ejecutar código en esta lección de Frontend Academy?

Sí. Cada lección de Frontend Academy incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.

Todas las lecciones de este curso

  1. Atomic Design: átomos, moléculas y organismos
  2. Configuración de un monorepo con Turborepo
  3. Microfrontends: Module Federation
  4. Estructura de carpetas basada en funcionalidades
← Volver a Frontend Academy