clean-react: React architecture example with Recoil and TDD

Why clean-react exists

clean-react is the application associated with Rodrigo Manguinho's React training. Its stated purpose is to demonstrate a React system built with Hooks, TypeScript, Recoil, TDD, Clean Architecture, SOLID, and several common design patterns. The intended audience is therefore not only developers looking for a polling application, but also engineers who want to study how those ideas can coexist in one repository.

The application domain is surveys for programmers. The README calls it 4Dev React and links documentation for an API at `fordevs.herokuapp.com/api-docs`. That external context matters because clean-react represents a client for a backend rather than a self-contained library. The repository includes the `src/`, `tests/`, and `public/` directories, along with Webpack templates and Cypress configuration, so the code is laid out as a browser application with separate test and configuration areas.

The README also links to an Udemy course. That makes the repository's educational intent explicit and distinguishes it from a reusable Clean Architecture starter. There are no GitHub releases, and the README does not describe a supported initialization command, deployment contract, or versioning policy for people who want to depend on the project as a package.

The React and TypeScript toolchain

The package metadata identifies TypeScript as the implementation language and lists React, Recoil, React Router DOM, and Axios among the libraries. The README explicitly names functional components and a broad selection of Hooks, including `UseState`, `UseContext`, `UseEffect`, `UseHistory`, `UseRef`, and `UseParams`. It also lists the Recoil APIs `Atom`, `UseRecoilState`, `UseResetRecoilState`, `UseRecoilValue`, and `UseRecoilSetState`.

That combination suggests two distinct state paths. Local interface state and effects can use React Hooks, while state intended for cross-component access can be represented with Recoil atoms and selectors through its Hooks. The README does not provide source excerpts showing where each choice is made, so that division cannot be asserted as a universal rule in the codebase. It is a feature set to inspect in `src/`, not a detailed state-management guide based on the README.

Routing is handled through React Router DOM, while Axios is the listed HTTP client. Webpack supplies separate development and production configurations, named `webpack.dev.js` and `webpack.prod.js`. SASS and animations appear in the library list, and React Flip Move is named for list transitions. These choices make the project useful for studying a frontend build with TypeScript compilation, asset handling, and production bundling, although the README does not document supported browser versions or Node.js versions.

Architecture claims and repository boundaries

The repository presents Clean Architecture as a method for distributing responsibilities across layers and decoupling components. It lists SRP, OCP, LSP, ISP, and DIP, together with Separation of Concerns, DRY, YAGNI, KISS, and Composition Over Inheritance. These principles describe design constraints rather than framework features.

The design pattern list includes Factory, Adapter, Composite, Decorator, Dependency Injection, Composition Root, Builder, and Proxy. The README also lists DDD, Reactive Programming, Use Cases, dependency diagrams, and modular design. Based on the repository layout, `src/` is the primary place to inspect those implementations and `tests/` is the associated test tree. The documentation does not include the directory tree inside `src/`, an import path, or a complete use-case example, so naming exact domain, data, and presentation modules would go beyond what is confirmed.

This distinction is important for adoption. The repository's description communicates a strong architectural objective, but the excerpt does not show how completely every principle is applied. A reader should use the source and tests as evidence rather than treating the topic list as proof that a specific boundary is implemented correctly. This is a study repository with a broad curriculum, not a compact package whose conventions can be inferred from the README alone.

Running the documented project commands

The README does not document installation steps such as package installation, version selection, or backend configuration. Based on the repository layout, `package.json` and `package-lock.json` contain the dependency and script definitions, but the documentation should not be treated as confirming a complete setup procedure.

The first usable command defined in `package.json` starts Webpack's development server through `dev:base`. The separate `dev` script opens the browser automatically:

npm run dev

The underlying command is documented as `npm run dev:base -- --open`, with `dev:base` invoking `webpack-dev-server --config webpack.dev.js`. The Cypress CI script contains `http-get://localhost:8080`, which identifies the port used by that CI path. The README does not explain whether the automatically opened development command is guaranteed to use that same port.

Before connecting the frontend to survey data, an engineer must also obtain and configure the API referenced by the README. The excerpt does not provide the required base URL, authentication procedure, or setup for a local backend. As a result, `npm run dev` verifies that the frontend toolchain can start, not that its data-loading flow will work end to end.

Jest and Cypress verification paths

The repository separates several testing workflows. `package.json` defines `test`, `test:watch`, `test:staged`, `test:ci`, and `test:coveralls`. The standard test command uses `cross-env NODE_ICU_DATA=node_modules/full-icu`, invokes Jest with `--passWithNoTests --no-cache --runInBand`, and suppresses the persistent cache. React Testing Library is listed for component-level testing, while Jest provides the test runner.

The documented all-tests command is:

npm test

The command allows a successful run when no tests are found, so a zero exit status alone should not be interpreted as proof that meaningful assertions ran. For a coverage-oriented run, the package defines `test:ci` with `--coverage`, and `test:coveralls` runs that command before sending `coverage/lcov.info` to Coveralls.

Browser-level behavior has a separate Cypress path. The package defines `test:cypress` to run `cypress open`.

The repository also defines `test:cypress:run` for `cypress run` and `test:cypress:ci`, which starts the development server, waits for `http-get://localhost:8080`, and then runs Cypress. This requires the build and API context expected by those tests. The README lists unit, integration, end-to-end, mocks, stubs, spies, fakes, and dummies, but it does not provide test names or explain which survey flows require a live backend.

Practical limits, alternatives, and operating cost

The clearest limitation is documentation depth. The README is broad but does not provide a local backend setup, environment variable contract, Node.js support policy, deployment procedure, or a concrete data-flow walkthrough. The repository also has no GitHub releases, so there is no release-based upgrade stream documented there. The last push was on 2026-09-09. That date is recent, but it does not establish a release cadence or compatibility promise.

A production team should also account for the toolchain. `package.json` lists React 17 type packages, Cypress 8, and TypeScript and ESLint packages. This does not prove that every dependency has a defect. It does mean adoption requires checking package compatibility and lockfile maintenance before copying the setup into a new service.

The license is GPL-3.0, and the package metadata records `GNU GPL3`. Teams should review that license against their intended distribution and linking model. This is a license identification point, not legal advice.

The real alternative is to build the same survey client with Next.js or a current React application framework and apply Clean Architecture at application boundaries. That approach changes the routing, rendering, data-fetching, and deployment model, while clean-react keeps explicit Webpack configuration, React Router DOM, Axios, Recoil, and a course-oriented layering exercise. Developers wanting concrete examples of Recoil and the named patterns may prefer clean-react. Teams needing a current framework migration path should not treat it as their starting point without checking dependency age and missing setup guidance.

Editorial conclusion

Developers learning Clean Architecture in React may adopt clean-react as a code study project, while teams seeking a maintained production framework or a documented install path should first confirm that its examples fit their current stack and verify the scripts in package.json against their environment.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. Project website
4. README
5. rmanguinho/clean-react on GitHub