Skip to main content

Introduction

hexagonal-react is a monorepo template that enforces hexagonal architecture (also known as the ports and adapters pattern) through ESLint rules and Turborepo.

The core principle is simple yet powerful: "If it compiles, it's architecturally correct."

This means architectural violations are caught at compile-time by ESLint, not during code review. If your code builds, you can be confident it follows clean architecture principles.

⚙️ Philosophy​

The core idea behind hexagonal-react is that architecture should be enforced by tooling, not by documentation and code review. Instead of trusting developers to follow architectural guidelines, this template makes violations impossible to compile.

Key principles:

  • Domain logic is completely independent from React and external dependencies
  • Ports define interfaces for external interactions (databases, APIs, etc.)
  • Use-cases orchestrate domain logic and ports without knowing concrete implementations
  • Adapters provide concrete implementations, but can only be imported in the DI container
  • UI components are pure and declarative, receiving ViewModels via props

In short: If it compiles, it's architecturally sound.

🧩 Key Advantages​

  • Compile-Time Safety – ESLint enforces architectural rules; violations fail the build
  • Framework Independence – Business logic is decoupled from React; easy to migrate or mix frameworks
  • Testability – Test domain and use-cases without React Testing Library or mocking frameworks
  • Swappable Implementations – Change databases, APIs, or ViewModels without touching business logic
  • Clear Boundaries – Developers always know where code belongs
  • Safe Architecture – Even if an AI or junior developer violates architecture, the build will fail
  • Modern Stack – React 19, Next.js 15, Vite 5, TypeScript, Turborepo, Tailwind
  • Code Generators – So you can write new features smoothly, quickly, and without breaking the Architecture

🚀 Expected Benefits​

  • Maximum flexibility thanks to powerful Architecture
  • Cleaner separation between business logic and UI
  • Easier to test domain logic without framework overhead
  • Swappable implementations (e.g., swap Prisma for in-memory storage)
  • Prevents architectural decay over time
  • Scalable organization by bounded contexts and modules

🧰 Ideal Use Cases​

  • Complex domains requiring clean separation of concerns (finance, healthcare, SaaS platforms, etc.)
  • Large teams where architectural consistency is critical
  • Multi-framework projects that need to share business logic across Next.js, Vite, React Native, etc.
  • Long-lived codebases where architectural decay is a concern
  • Highly testable applications where domain logic must be tested independently of React

🧭 TLDR;​

hexagonal-react is a monorepo template that enforces hexagonal architecture through ESLint, ensuring your React applications maintain clean separation of concerns at compile-time.