react-philosophies: a reading list for how you write React, not a package you install

What react-philosophies actually is, and who it is written for

The repository contains four top-level entries: LICENSE, README.md, WIP_CODE_QUALITY_CHECKLIST.md and WIP_PR_TEMPLATE.md. There is no package manifest, no build script and no source directory. The README describes the project as "things I think about when I write React code", and the introduction says it is "just guidelines and NOT rigid rules". That framing is the whole product. You are not installing a linter; you are reading a position paper on how one experienced developer approaches React.

The intended reader is someone who already writes React and reviews other people's React. The introduction says the ideas sit "at the back of my mind whenever I review someone else's code or my own", which points at code review and refactoring rather than onboarding. A beginner can read it, but the entries assume familiarity with hooks, component composition and the difference between state that belongs in a component and state that belongs in a store. The document also states that it is a living document and will evolve as the author's experience grows, and the README carries a badge reading "Forever a work in progress". Treat the text as an opinion you can argue with, not a specification you can comply with.

The four-part structure: bare minimum, design, performance, testing

The table of contents lists six entries: Introduction, The Bare Minimum, Design for happiness, Performance tips, Testing principles, and Insights shared by others. The author admits the split was hard to draw. A collapsible section in the README says it "was actually difficult for me to separate my thoughts into the design, performance, and testing", and that many designs intended for maintainability also make an application faster and easier to test. That admission matters when you use the document: a tip filed under performance may really be a design tip, and searching for a category will not reliably find it.

The last section is different in kind. Insights shared by others is an open slot where readers submit their own ideas, and the README invites pull requests and issues for that section specifically, along with corrections to broken links, grammar, formatting and typographical errors. The introduction also names its influences: Sandi Metz, the Zen of Python (PEP 20), the Zen of Go, trekhleb/state-of-the-art-shitcode, droogans/unmaintainable-code and sapegin/washingcode-book. It describes its own content as "mostly techniques which are variations of basic refactoring methods, SOLID principles, and extreme programming ideas... just applied to React specifically". If you have read those sources, a lot of react-philosophies will feel like translation rather than discovery, which is either the point or a reason to skip it, depending on what you already know.

Getting the text and putting the bare minimum into a review

There is nothing to install. The README is the artifact, and the repository has no homepage, so the project is read on GitHub. Clone it if you want it locally beside your code:

git clone https://github.com/mithi/react-philosophies.git
cd react-philosophies

After the clone you get the four top-level entries listed earlier. Open README.md and use the table of contents links, which jump to the numbered sections. A first real use is to take the section titled The Bare Minimum and read it against a pull request you are already reviewing. The README does not prescribe a checklist format for this, so the practical move is to quote the relevant line in the review comment and let the author respond to the argument rather than to you.

The repository also carries WIP_CODE_QUALITY_CHECKLIST.md and WIP_PR_TEMPLATE.md. The WIP prefix is in the filenames, so both are unfinished. If you want to adapt the PR template for your own repository, read it first and expect gaps rather than a finished form. The README does not document how these two files relate to the numbered sections, and it does not explain what is still missing from them.

Where the document stops being useful

The most concrete limitation is stated by the author: these are guidelines and not rigid rules, and the README describes the content as a living document. Nothing in the repository enforces anything. There is no rule set to run in CI, no configuration file, and no automated check. If your team's actual problem is that reviewers disagree and nobody has authority, a document whose own introduction disclaims rigidity will not settle the argument. You would need to convert the sections into your own lint rules or review checklist, and the repository gives you no starting configuration for that.

The second limitation is the overlap the author already flagged. Because design, performance and testing were hard to separate, a reader looking for "what should I do about this slow render" may find the answer under design, and vice versa. The table of contents is the only index; there is no searchable tag system and no per-tip identifier you can cite precisely. In a review comment you can link a section heading, but you cannot point at item number twelve.

The third is staleness risk. The last push to the default branch was on 2026-08-29, and the two most recent releases are v1.0.1 from 2022-03-11 and v1.0.2 from 2023-04-09. React itself moves faster than that release cadence. The README does not state which React version the guidance targets, so before you apply a performance tip, check it against the React version your project actually runs.

How it compares with Tao of React and rule-enforcing tools

The closest comparison in the related searches is Tao of React, another prose guide to React practice. Both are documents rather than dependencies, and both expect you to translate opinion into your own conventions. The difference in approach here is the explicit split into a bare minimum, design, performance and testing, plus an open section for reader-submitted insights. Tao of React is written as a structured set of principles by a single author; react-philosophies mixes the author's own guidelines with a contributions section and a list of influences, so part of what you read is curated from elsewhere rather than original.

Against a rule-enforcing tool the difference is sharper. A linter or a formatter produces a pass or fail on a line of code and can run in CI. react-philosophies produces a paragraph you either agree with or do not. There is no overlap in mechanism, so they are not substitutes; the honest framing is that the document tells you what to argue about and a tool tells you when you have stopped arguing. If you need the second thing, this repository is the wrong place to look, and the README offers no path from the text to an enforced rule.

Licence, maintenance and the cost of keeping up

The repository is licensed CC-BY-SA-4.0, a Creative Commons licence intended for text rather than code. That fits a project whose deliverable is prose, and it has a practical consequence: the ShareAlike term applies to adaptations, so if you copy sections into an internal handbook and modify them, the licence conditions attach to what you produce. This is a description of the licence identifier, not legal advice; read the LICENSE file and decide with whoever handles this at your organisation.

The translations listed in the README are separate repositories, not directories here: a Chinese translation by @Leecason and a Korean translation by @lim-jiwoo, each pinned to a commit snapshot of an earlier version (v1.0.1 and v1.0.2 respectively). If you read a translation, you are reading an older state of the document, and the README's snapshot badges make that explicit. The upgrade cost of the project itself is near zero, because there is no dependency to bump. The cost that does exist is re-reading: since the document evolves, a section you quoted in a review six months ago may have been reworded or moved. Nothing in the repository announces what changed between pushes, so the only reliable check is to open the file and read the section again.

Editorial conclusion

Adopt it as a shared reference when your team already writes React and argues about the same patterns in review, because the repository is a document rather than a dependency and the README states outright that these are guidelines and not rigid rules. Do not adopt it if you need an enforced rule set, an ESLint plugin or a migration path, since no such artifact exists in the repository. Before you rely on it, check the last push date, read the WIP_CODE_QUALITY_CHECKLIST.md file to see whether its unfinished state suits you, and confirm the CC-BY-SA-4.0 terms against how you intend to reuse the text.

Frequently asked questions

Official sources

1. Issues
2. License: CC-BY-SA-4.0
3. mithi/react-philosophies on GitHub
4. README
5. Releases