Skip to content

ADR-0007: Select React and TanStack Query for Frontend

  • Status: Accepted
  • Date: 2025-09-11
  • Authors: Senior Systems Analyst

Context and Problem Statement

The project requires a modern, robust, and performant frontend to serve as the user interface for the enterprise console. We need a technology stack that provides a strong developer experience, handles complex server state management efficiently, and is supported by a large community and ecosystem.

Considered Options

  • Option 1: Other Major Frameworks (e.g., Angular, Vue)

    • Description: Use another popular frontend framework.
    • Pros:
      • Both are mature and capable frameworks with strong ecosystems.
    • Cons:
      • May not align with the current skill set of the team, potentially slowing down initial development.
      • Each has a different approach to state management that would need to be evaluated.

  • Option 2: React with a dedicated Server State Library (Chosen)

    • Description: Use React as the core UI library. For managing the lifecycle of data from the server (fetching, caching, synchronizing, updating), we will use a dedicated library like TanStack Query (formerly React Query) instead of relying solely on a global state manager or simple useEffect hooks. For minimal global UI state, we will use a lightweight manager like Zustand.
    • Pros:
      • Declarative and Efficient Server State: TanStack Query declaratively handles caching, background refetching, and request deduplication out-of-the-box, significantly reducing boilerplate and eliminating common bugs related to stale data.
      • Excellent Developer Experience: Separates the concern of managing server cache from global client state, leading to cleaner, more maintainable code.
      • Strong Ecosystem: React has the largest ecosystem of libraries and tools, including mature component libraries like Shadcn/UI which fits our stack perfectly.
      • Team Familiarity: Aligns with the common skill set of modern frontend developers.
    • Cons:
      • Requires developers to learn the specific patterns of TanStack Query, which has a slight learning curve compared to basic fetching.

Decision

We will build the frontend using React, with TanStack Query as the primary tool for all server state management and Zustand for minimal global client state. This stack provides the best combination of developer experience, performance, and robustness for a data-intensive enterprise application. The detailed implementation of this stack is specified in the Frontend Technical Requirements Document.

Consequences

Positive

  • The amount of manual data-fetching and state-management code will be drastically reduced.
  • The application will feel more responsive and up-to-date due to TanStack Query's automatic refetching and caching strategies.
  • The clear separation between server cache and client state will make the application easier to reason about and debug.

Negative

  • We are adding two key dependencies (TanStack Query, Zustand) to the project that the team must learn and master. The benefits are deemed to far outweigh this initial learning investment.