Clean Architecture in JavaScript: Best Practices & Examples

Introduction

The scalability and maintainability of modern JavaScript applications require clean architecture. As JavaScript frameworks like React, Next.js, and Node.js evolve rapidly, following a well-structured architecture is necessary to keep pace with rapid changes.

In this article, we'll explore the key principles of clean architecture with examples and explain why it's important.

What is Clean Architecture?

Clean Architecture encourages a clear division of responsibilities by isolating the essential business from dependencies on specific technologies like frameworks, databases, or UI. This simplifies testing and future development.

Key Principles of Clean Architecture

Independence from UI & Frameworks – Business logic should not depend on the UI layer (such as React or Vue) or external libraries.
Separation of Concerns – Group related tasks into separate, independent sections of your application, ensuring that each layer focuses on a distinct responsibility.
Dependency Inversion – Design your code so that high-level modules are not dependent on low-level modules; both should depend on abstractions.
Testability – Each layer should be easily testable in isolation.

Layers of Clean Architecture in JavaScript

1. Entities (Business Logic Layer)

Entities define core business rules and should remain pure and framework-agnostic.

Example: A User entity in a Node.js application:

class User {
  constructor(name, email) {
    if (!email.includes("@")) throw new Error("Invalid Email");
    this.name = name;
    this.email = email;
  }
}

2. Use Cases (Application Layer)

This layer contains interactors, defining how business logic is executed.

Example: A user registration use case that ensures unique emails:

class RegisterUser {
  constructor(userRepository) {
    this.userRepository = userRepository;
  }

  async execute(user) {
    const existingUser = await this.userRepository.findByEmail(user.email);
    if (existingUser) throw new Error("User already exists");

    return this.userRepository.save(user);
  }
}

3. Interface Adapters (Controllers & Services)

This layer handles input/output, connecting the business logic with the outside world (UI, API).

Example: A controller handling HTTP requests in Express.js:

app.post("/register", async (req, res) => {
  try {
    const user = new User(req.body.name, req.body.email);
    const registerUser = new RegisterUser(userRepository);
    const newUser = await registerUser.execute(user);
    
    res.status(201).json(newUser);
  } catch (error) {
    res.status(400).json({ error: error.message });
  }
});

4. Frameworks & Drivers (Infrastructure Layer)

This includes databases, APIs, external libraries, and UI frameworks.

Example: A repository pattern to separate business logic from the database:

class UserRepository {
  constructor(database) {
    this.database = database;
  }

  async findByEmail(email) {
    return this.database.find(user => user.email === email);
  }

  async save(user) {
    this.database.push(user);
    return user;
  }
}

New Trends in JavaScript Clean Architecture

1. Microservices & Serverless – Clean Architecture is applied in microservices & serverless apps using AWS Lambda, Firebase Functions, and Vercel Edge Functions.

2. Modular Monoliths – Many teams prefer modular monoliths with well-defined layers before scaling instead of breaking into microservices early.

3. TypeScript Adoption – TypeScript enhances Clean Architecture by enforcing type safety across layers.

4. DDD (Domain-Driven Design) Integration – Many developers are integrating Domain-Driven Design (DDD) to refine business logic structuring further.

Here's the actual folder structure I often follow for building scalable React apps.

/src
│
├── /app                    # App bootstrapping
│   ├── App.tsx
│   ├── index.tsx
│   └── /providers
│       ├── ReactQueryProvider.tsx
│       └── ThemeProvider.tsx
│
├── /domains                # Business logic (pure, testable, framework-agnostic)
│   └── user
│       ├── /entities
│       │   └── User.ts
│       ├── /value-objects
│       │   └── Email.ts
│       ├── /use-cases
│       │   └── registerUser.ts
│       └── /services
│           └── UserService.ts
│
├── /infrastructure         # External interfaces & integrations
│   ├── /http
│   │   └── axiosClient.ts
│   ├── /react-query         # ✅ Data fetching layer
│   │   └── /user
│   │       ├── useGetUser.ts
│   │       └── useRegisterUser.ts
│   └── /user
│       └── UserRepository.ts
│
├── /ui                     # ✅ Component-Driven Development Layer
│   ├── /components         # Reusable, testable components (UI atoms, molecules)
│   │   ├── Button.tsx
│   │   └── TextInput.tsx
│   ├── /widgets            # Small feature-oriented units (forms, cards)
│   │   └── UserCard.tsx
│   └── /features           # Feature-specific UI (bundled with queries + logic)
│       └── /user
│           ├── UserForm.tsx
│           ├── useUserForm.ts  # Local form logic (Zod, React Hook Form, etc.)
│           └── index.ts        # Export entry
│
├── /pages                  # Route-level views (Next.js or React Router)
│   └── RegisterPage.tsx
│
├── /shared                 # Global helpers, hooks, themes
│   ├── /hooks
│   │   └── useDebounce.ts
│   ├── /theme
│   │   └── colors.ts
│   └── /utils
│       └── formatDate.ts
│
├── /tests                  # TDD: Unit, integration & e2e
│   ├── /unit
│   │   └── userService.test.ts
│   ├── /integration
│   │   └── userFlow.test.tsx
│   └── /e2e
│       └── registerUser.e2e.ts
│
└── /config
    ├── routes.ts
    └── react-query-config.ts

Conclusion

Applying 'clean architecture' in JavaScript ensures a scalable, maintainable, and testable application. Ultimately, embracing clean architecture in JavaScript is like investing in the future of your application. It keeps the business logic separate from frameworks, databases, and UI, hence enabling testing and future expansion, not only robust and reliable today but also flexible and ready for whatever tomorrow brings.