React.js Koans: A Test-Driven Primer for React Basics, Frozen in 2016

The Problem: Learning React Without a Project to Build

Most React tutorials walk you through building an app. You follow along, type the code, and hope the result works. React.js Koans takes a different route. It gives you a set of exercises where tests already exist and are failing. Your job is to edit the code in the exercises directory until the tests pass. The README states that the only prerequisite is JavaScript, specifically the ECMAScript 2015 standard. This targets a beginner who knows JavaScript but has never touched React. The koan format, borrowed from the Zen koan tradition, forces you to discover the answer by making the test green, not by reading a solution. It is a practical, hands-on approach that avoids the passive learning of a video or a book chapter. The project was maintained by Arkency, a Polish software company that also runs the React Kung Fu blog and sells a related book. The intended audience is clear: someone who wants to learn React by doing, with immediate feedback from a test runner.

How the Exercises and Tests Are Organized

The repository layout is explicit. The exercises directory contains the files you edit. The koans directory holds the source of all exercises, and test contains the tests that verify your work. The src directory contains files compiled from exercises, and build holds sources for a web browser version. The flow is: you edit a file in exercises, run the test suite, see a failure, and then adjust your code until the test passes. The README warns you not to peek at the test files because they contain spoilers. That means the tests are not just a verification tool; they are part of the learning material. You infer the expected behavior from the test name and the failure message. This is a strong pedagogical device, but it has a flaw. If you get stuck, you have no documentation or hints beyond the test output. There are video walkthroughs for installation and the first two exercises, which help, but the rest of the exercises require self-reliance. The order matters: the instructions say you must do the exercises in the given order, which suggests each koan builds on the previous one, introducing React concepts incrementally.

Getting It Running: Setup and Commands

The setup is straightforward, but it has a catch. The README says you need Node.js and Python 2 installed. Python 2 is a significant detail because it is end-of-life and not present by default on modern systems. The installation steps are: git clone, cd into the directory, and run npm run setup. That command presumably installs dependencies and compiles the initial state. After setup, you run npm run test to execute the tests. If you want automatic test runs on file changes, you use npm run watch. There is also an optional local web server: npm run start and visit http://localhost:8080/. That server lets you see your changes live in the browser, which is useful for exercises that render UI. The commands are simple, but the Python 2 requirement is a red flag. The project was last pushed on January 2, 2016, and the release 1.0.0 dates from that day. Node.js and Python ecosystems have moved on. The npm dependencies from that era may not install cleanly on a current Node version, and Python 2 is not available on many systems. The setup script may fail or need manual intervention. The README does not mention any Node version range, so you are on your own to make it work in 2025.

The Learning Content: What the Exercises Cover

The README does not list the specific exercises, but it describes the project as a set of practical exercises that take you from square one. The mention of ECMAScript 2015 suggests the exercises use modern JavaScript syntax like arrow functions, const, and classes. The test suite is likely built with a framework like Jasmine or Mocha, but the README does not specify. The koan structure implies a progression from basic component creation to more complex concepts like state, props, and lifecycle methods. The README links to a blog post about why keys are important in React, which hints that the exercises cover dynamic children and key usage. That is a core React concept that trips up many beginners. The video walkthroughs for exercises #1 and #2 indicate that the first exercises are simple, probably rendering a static element. The project is not a comprehensive React course; it is a set of focused exercises that teach the fundamentals. The README suggests continuing with the React by example book after finishing the koans, which implies the koans cover only the basics. This is a strength: it is short and focused. But it also means you will not learn advanced topics like performance optimization or integration with other libraries.

The Maintenance Problem: A Snapshot from 2016

The last push to the repository was on January 2, 2016, and the latest release is 1.0.0 from that same day. The project is not archived, but it is effectively frozen. The README does not mention any plans for updates. This is a major limitation for anyone considering it today. React has changed dramatically since 2016. The introduction of hooks in React 16.8 fundamentally changed how components are written. The koans likely use class components and lifecycle methods, which are still supported but no longer the default. The build tooling is also outdated. The project uses Babel to compile ES2015, and the test runner is tied to that era. On a modern system, you may encounter dependency conflicts or security warnings. The README does not provide any guidance for troubleshooting. The videos linked in the README may also be outdated, showing old installation procedures. If you are a beginner, you might learn patterns that are no longer recommended. This is not a fault of the original authors; it is the nature of a learning project that has not been maintained. The question is whether the fundamentals are still valid. React's core concepts like components, props, state, and keys remain the same, so the koans can still teach those. But you will need to adapt the code to modern syntax and possibly update the test setup yourself.

Alternatives: Modern Test-Driven React Learning

If you want a test-driven approach to learning React but need something current, there are alternatives. One option is to build your own koans using Jest and React Testing Library. You can create a series of failing tests that require you to implement components, and you control the difficulty and the React version. This is a do-it-yourself approach that gives you full control, but it requires you to design the exercises, which takes time. Another alternative is the official React documentation, which includes interactive tutorials and a built-in test-like environment for the tic-tac-toe game. That tutorial is not test-driven, but it is up to date and covers hooks. A third option is online platforms like freeCodeCamp, which have React challenges with immediate feedback, but they do not use a local test runner. The key difference is that React.js Koans forces you to write code locally and run tests, which mimics a real development workflow. Modern alternatives often run in the browser or provide a guided path. The trade-off is between learning the fundamentals with an outdated but structured approach, or using current tools that may not have the same koan-style discipline. If you specifically want the koan format, you might find a community-maintained fork, but the README does not mention any.

Licence and Cost: MIT with a Commercial Upsell

The project is licensed under MIT, which means you can freely use, modify, and distribute it. The README does not impose any restrictions beyond the standard MIT terms. There is no cost for the koans themselves. However, the README includes a promotional section for the React by example book, with a 20% discount code REACTKOANS. That is a clear upsell. The book is not required to complete the koans, but it is positioned as a follow-up. The README also links to Arkency's blog and hiring page, so the project serves as a marketing tool for the company. This is not a problem, but it is worth noting that the project has a commercial angle. The MIT licence means you can fork the project and update it yourself, which is a practical option if you want to keep the koan approach but modernize the content. You would need to replace the old Babel setup with a current build tool and rewrite the tests to use a modern testing library. That is a significant effort, but it is allowed by the licence. The README does not provide any contribution guidelines, so if you want to help, you would need to figure out the workflow on your own.

Editorial conclusion

Adopt React.js Koans if you are a JavaScript developer who wants a hands-on, test-driven introduction to React's core concepts and you are comfortable with an ES2015-era toolchain. Do not use it if you need to learn modern React with hooks, function components, or current build tools, because the project has not been updated since 2016. Before starting, verify that your Node.js version can run the old Babel and test setup, and be ready to adapt the exercises to your own environment. The project is a snapshot of React's past, useful for understanding fundamentals, but not a guide to today's React.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes