Clean Architecture en Frontend (React / Next.js + TypeScript)

Edgar Joaquin — Thu, 17 Sep 2026 18:20:54 +0000

Clean Architecture en Frontend (React / Next.js + TypeScript)

Guía práctica con la estructura de carpetas/archivos que suele usarse al aplicar Clean Architecture en un frontend. La idea central es separar el código en capas con responsabilidades claras, donde las capas internas (dominio) no dependen de las externas (UI, frameworks, APIs).

Las capas, de adentro hacia afuera

Domain (Entidades) — Reglas de negocio puras. No depende de nada externo (ni de React, ni de Axios, ni de Next).
Application (Casos de uso) — Orquesta la lógica de negocio usando el dominio. Define interfaces (contratos) que la infraestructura implementará.
Infrastructure (Adaptadores) — Implementaciones concretas: llamadas HTTP, localStorage, SDKs de terceros, repositorios.
Presentation (UI) — Componentes, páginas, hooks, estado de UI. Depende de application, nunca al revés.
La regla de oro: las dependencias siempre apuntan hacia adentro (presentation → application → domain), nunca al revés.

Ejemplo 1: React (Vite) + TypeScript

src/
├── domain/
│   ├── entities/
│   │   ├── User.ts
│   │   ├── Product.ts
│   │   └── Order.ts
│   ├── value-objects/
│   │   ├── Email.ts
│   │   └── Money.ts
│   ├── errors/
│   │   └── DomainError.ts
│   └── repositories/                 # Interfaces (contratos), no implementación
│       ├── IUserRepository.ts
│       └── IProductRepository.ts
│
├── application/
│   ├── use-cases/
│   │   ├── user/
│   │   │   ├── GetUserById.ts
│   │   │   ├── UpdateUserProfile.ts
│   │   │   └── DeleteUser.ts
│   │   └── product/
│   │       ├── GetProductList.ts
│   │       └── CreateProduct.ts
│   ├── dtos/
│   │   ├── UserDTO.ts
│   │   └── ProductDTO.ts
│   └── mappers/
│       ├── UserMapper.ts             # Entity <-> DTO
│       └── ProductMapper.ts
│
├── infrastructure/
│   ├── http/
│   │   ├── axiosClient.ts
│   │   └── endpoints.ts
│   ├── repositories/                 # Implementan las interfaces del domain
│   │   ├── HttpUserRepository.ts
│   │   └── HttpProductRepository.ts
│   ├── storage/
│   │   └── LocalStorageService.ts
│   └── config/
│       └── env.ts
│
├── presentation/
│   ├── components/
│   │   ├── common/
│   │   │   ├── Button.tsx
│   │   │   └── Input.tsx
│   │   └── user/
│   │       ├── UserCard.tsx
│   │       └── UserForm.tsx
│   ├── pages/
│   │   ├── UserProfilePage.tsx
│   │   └── ProductListPage.tsx
│   ├── hooks/
│   │   ├── useUser.ts                # Consume los use-cases
│   │   └── useProducts.ts
│   ├── context/
│   │   └── AuthContext.tsx
│   ├── routes/
│   │   └── AppRouter.tsx
│   └── styles/
│       └── globals.css
│
├── shared/
│   ├── utils/
│   │   ├── formatDate.ts
│   │   └── validators.ts
│   ├── constants/
│   │   └── index.ts
│   └── types/
│       └── common.types.ts
│
├── di/                                # Inyección de dependencias (composition root)
│   └── container.ts
│
├── App.tsx
└── main.tsx

Cómo fluye una petición (ejemplo: obtener un usuario)

UserProfilePage.tsx
  → useUser.ts (hook)
    → GetUserById.ts (use-case, application)
      → IUserRepository.ts (interfaz, domain)
        ← HttpUserRepository.ts (implementación real, infrastructure)

El hook y la página no saben si el dato viene de una API REST, GraphQL o localStorage. Eso vive solo en infrastructure/.

Ejemplo 2: Next.js (App Router) + TypeScript

Next.js añade la carpeta app/ como capa de ruteo/presentación, pero el resto de capas se mantienen igual, normalmente dentro de src/.

src/
├── app/                               # Solo ruteo, layouts y páginas (Next App Router)
│   ├── layout.tsx
│   ├── page.tsx
│   ├── users/
│   │   ├── page.tsx
│   │   └── [id]/
│   │       └── page.tsx
│   ├── products/
│   │   ├── page.tsx
│   │   └── loading.tsx
│   └── api/                           # Route handlers (si se usan como BFF)
│       └── users/
│           └── route.ts
│
├── domain/
│   ├── entities/
│   │   ├── User.ts
│   │   └── Product.ts
│   ├── value-objects/
│   │   └── Email.ts
│   ├── errors/
│   │   └── DomainError.ts
│   └── repositories/
│       ├── IUserRepository.ts
│       └── IProductRepository.ts
│
├── application/
│   ├── use-cases/
│   │   ├── user/
│   │   │   └── GetUserById.ts
│   │   └── product/
│   │       └── GetProductList.ts
│   ├── dtos/
│   │   └── UserDTO.ts
│   └── mappers/
│       └── UserMapper.ts
│
├── infrastructure/
│   ├── http/
│   │   └── fetchClient.ts
│   ├── repositories/
│   │   ├── HttpUserRepository.ts
│   │   └── HttpProductRepository.ts
│   ├── server/                        # Repos que corren en Server Components/Actions
│   │   └── ServerUserRepository.ts
│   └── config/
│       └── env.ts
│
├── presentation/
│   ├── components/
│   │   ├── common/
│   │   │   └── Button.tsx
│   │   └── user/
│   │       └── UserCard.tsx
│   ├── hooks/
│   │   └── useUser.ts                 # Para Client Components
│   └── view-models/
│       └── UserViewModel.ts           # Formatea DTOs para la vista
│
├── shared/
│   ├── utils/
│   │   └── formatDate.ts
│   └── types/
│       └── common.types.ts
│
├── di/
│   └── container.ts
│
└── middleware.ts

Diferencias clave respecto a React puro

app/page.tsx (Server Component) puede llamar directamente a un use-case desde application/, sin pasar por un hook, ya que corre en el servidor.
Los Client Components siguen usando hooks de presentation/hooks/ para invocar use-cases (a través de una API route o Server Action).
infrastructure/server/ separa repositorios que solo pueden ejecutarse en servidor (con acceso directo a BD, secretos, etc.) de los que corren en cliente.

Reglas prácticas para no romper la arquitectura

domain/ nunca importa nada de application/, infrastructure/ o presentation/.
application/ solo importa de domain/ (entidades e interfaces), nunca de infrastructure/ directamente — recibe las implementaciones por inyección de dependencias.
infrastructure/ implementa las interfaces definidas en domain/repositories/.
presentation/ (componentes, páginas, hooks) solo llama a application/use-cases, nunca a infrastructure/ directamente.

El "cableado" (qué implementación concreta se usa en cada caso) se centraliza en di/container.ts.

Ejemplo mínimo de código (para ver las capas en acción)

// domain/repositories/IUserRepository.ts
export interface IUserRepository {
  getById(id: string): Promise<User>;
}

// application/use-cases/user/GetUserById.ts
export class GetUserById {
  constructor(private userRepository: IUserRepository) {}
  execute(id: string) {
    return this.userRepository.getById(id);
  }
}

// infrastructure/repositories/HttpUserRepository.ts
export class HttpUserRepository implements IUserRepository {
  async getById(id: string) {
    const res = await fetch(`/api/users/${id}`);
    return res.json();
  }
}

// presentation/hooks/useUser.ts
const getUserById = new GetUserById(new HttpUserRepository());
export function useUser(id: string) {
  const [user, setUser] = useState<User | null>(null);
  useEffect(() => { getUserById.execute(id).then(setUser); }, [id]);
  return user;
}

Con esto puedes, por ejemplo, cambiar HttpUserRepository por FakeUserRepository en tus tests sin tocar ni el use-case ni el componente.

La diferencia principal en Next.js es que app/ queda como capa de ruteo pura, y aparece una carpeta infrastructure/server/ para separar los repositorios que solo pueden correr en el servidor (Server Components, Server Actions) de los que se usan desde el cliente.

Arquitectura limpia en proyecto de Nodejs + Typescript + MongoDB

Edgar Joaquin — Fri, 05 Apr 2024 20:55:51 +0000

Estructura

├── api
│ ├─── controllers
│ │ ├─── usuarios.controller.ts
│ │ ├─── publicaciones.controller.ts
│ │ ├─── seguidores.controller.ts
│ │ ├─── ...
│ ├─── middlewares
│ │ ├─── auth.middleware.ts
│ │ ├─── error.middleware.ts
│ │ ├─── ...
│ ├─── routes
│ │ ├─── usuarios.routes.ts
│ │ ├─── publicaciones.routes.ts
│ │ ├─── seguidores.routes.ts
│ │ ├─── ...
│ ├─── services
│ │ ├─── usuarios.service.ts
│ │ ├─── publicaciones.service.ts
│ │ ├─── seguidores.service.ts
│ │ ├─── ...
│ ├─── utils
│ │ ├─── utils.ts
│ ├─── index.ts
├── application
│ ├─── config
│ │ ├─── app.config.ts
│ │ ├─── database.config.ts
│ │ ├─── ...
│ ├─── models
│ │ ├─── usuario.model.ts
│ │ ├─── publicacion.model.ts
│ │ ├─── seguidor.model.ts
│ │ ├─── ...
│ ├─── repositories
│ │ ├─── usuarios.repository.ts
│ │ ├─── publicaciones.repository.ts
│ │ ├─── seguidores.repository.ts
│ │ ├─── ...
│ ├─── services
│ │ ├─── usuarios.service.ts
│ │ ├─── publicaciones.service.ts
│ │ ├─── seguidores.service.ts
│ │ ├─── ...
│ ├─── utils
│ │ ├─── utils.ts
│ ├─── index.ts
├── domain
│ ├─── entities
│ │ ├─── usuario.entity.ts
│ │ ├─── publicacion.entity.ts
│ │ ├─── seguidor.entity.ts
│ │ ├─── ...
│ ├─── useCases
│ │ ├─── usuarios.usecase.ts
│ │ ├─── publicaciones.usecase.ts
│ │ ├─── seguidores.usecase.ts
│ │ ├─── ...
│ ├─── index.ts
├── infrastructure
│ ├─── adapters
│ │ ├─── database.adapter.ts
│ │ ├─── ...
│ ├─── database
│ │ ├─── index.ts
│ ├─── repositories
│ │ ├─── usuarios.repository.ts
│ │ ├─── publicaciones.repository.ts
│ │ ├─── seguidores.repository.ts
│ │ ├─── ...
│ ├─── utils
│ │ ├─── utils.ts
│ ├─── index.ts
├── index.ts
├── package.json
├── tsconfig.json

Explicación:

api: Contiene los controladores, middlewares y rutas de la API.

application: Contiene la configuración de la aplicación,

modelos, repositorios, servicios y utilidades.

domain: Contiene las entidades y casos de uso del dominio de la aplicación.

infrastructure: Contiene los adaptadores, la base de datos y los repositorios de la infraestructura.

index.ts: Archivo principal que inicia la aplicación.

package.json: Contiene las dependencias del proyecto.

tsconfig.json: Contiene la configuración del compilador TypeScript.

Consideraciones

Esta es una estructura de archivos básica, puede modificarse según las necesidades específicas del proyecto.

Se recomienda usar un contenedor de dependencias para inyectar las dependencias en las diferentes clases.

Se pueden usar herramientas como NestJS para facilitar la implementación de Clean Architecture.

DEV Community: Edgar Joaquin

Clean Architecture en Frontend (React / Next.js + TypeScript)

Arquitectura limpia en proyecto de Nodejs + Typescript + MongoDB