kentcdodds/bookshelf: the Epic React workshop repo, and what its setup script actually does

What kentcdodds/bookshelf is, and who the workshop is for

This repository is the code that accompanies the Build an Epic React App workshop on EpicReact.Dev. The README describes it as a huge workshop in which you build an application from scratch using widely supported and proven tools and techniques, covering everything from the absolute basics to the tricky parts of real React apps. The subject is the bookshelf app itself: a book tracking UI hosted at bookshelf.lol.

The intended reader already knows React. The prerequisites section says you will want experience with React before going through the material, and that the lessons get progressively more advanced. That is a real constraint rather than a formality. The dependency list includes react-query pinned at 2.1.1, react-router 6.3.0, msw 0.42.1 and codegen.macro, and the exercises assume you can read code that uses them. If any of those names are unfamiliar, the README points you back to other parts of EpicReact.Dev rather than explaining them here.

One detail worth knowing before you clone anything: the videos were recorded against React ^16.13, while the repository has been updated to React ^18. The README says the differences are minor and that relevant ones are noted in the instructions. Expect the recorded walkthrough and the code you have checked out to diverge in places, and trust the INSTRUCTIONS.md file over the video when they disagree.

How the workshop repo is put together

The layout is a single create-react-app project with the workshop machinery layered on top. src/ holds the application, cypress/ holds end-to-end specs, scripts/ holds the tooling that setup.js and go.js drive, and the top level carries jest.config.js, cypress.config.js, jsconfig.json and netlify.toml. There is no published package to import; package.json sets private to true and the name is simply bookshelf.

The exercise mechanism is branch-based. The README states that the exercises live in different branches and that each branch changes INSTRUCTIONS.md to contain the instructions for that exercise. Running node go lets you choose which exercise to work on, and running it again later lets you jump to an extra credit or a specific part of an exercise, updating your exercise files to the matching version. That is the core of the data flow: you are not reading a static tutorial, you are moving your working tree between prepared states.

The app itself runs against mocked HTTP rather than a real backend. msw is a dependency, and the data model in the README describes a User with id and username and a List Item with id, bookId, ownerId, rating (where -1 means no rating and 1 to 5 is a rating), notes, startDate and finishDate. Because the API is mocked in the browser, there is no server to stand up and no database to seed. That keeps the workshop self-contained, but it also means nothing here teaches you how the client behaves against a slow or failing real service beyond what the mocks simulate.

Test coverage comes from two places. Jest runs in watch mode through npm test, and Cypress is configured separately. The README is candid about the limits of the Jest suite: sometimes you can accomplish the task and the tests still fail if you implement things differently than the author does in the solution, so the tests are not a complete authority. Treat them as a signal, not a specification.

Installing bookshelf and running the first exercise

The README lists three system requirements: git v2.13 or greater, NodeJS >=16, and npm v8.16.0 or greater, all available on your PATH. The package.json engines field repeats the Node and npm floors. Check them before cloning, because the setup script assumes them.

git --version
node --version
npm --version

If you plan to commit your work, the README suggests forking first and cloning your fork rather than the upstream repository. Then the documented setup is three commands. The setup step may take a few minutes.

git clone https://github.com/kentcdodds/bookshelf.git
cd bookshelf
node setup

If node setup fails, the README gives a fallback of npm install followed by npm run validate. If that still does not work and you know Docker, docker-compose up is the third option; the compose file builds the local Dockerfile, mounts ./src into /app/src and publishes port 3000. The Dockerfile itself runs NO_EMAIL_AUTOFILL=true node setup during the image build and then starts with npm start.

npm install
npm run validate

To see the app, run the start script. The README notes this is a standard react-scripts application, so your browser should open on the dev server once it compiles.

npm start

To begin the exercises rather than just run the app, use the go script and then open INSTRUCTIONS.md in the exercise branch you selected. The README is explicit that the point is not to finish all the material, but to get you thinking about the right questions before the author walks through the solution.

node go

For the test suite, npm test starts Jest in watch mode. Cypress is configured through cypress.config.js if you want the end-to-end specs as well.

The emoji comment system is the actual teaching interface

Most of the instruction inside the source files arrives as comments tagged with named emoji characters. The README defines them: Kody the Koala marks something specific you should do, Marty the Money Bag gives tips and sometimes code, Hannah the Hundred offers extra challenges, Nancy the Notepad prompts you to take notes, Olivia the Owl gives best practice notes with links, Dominic the Document links to documentation, Berry the Bomb marks code to delete, Matthew the Muscle indicates an exercise, Chuck the Checkered Flag indicates a final step, Peter the Product Manager frames what users want, and Alfred the Alert appears in test failures with possible explanations.

This is a genuinely unusual documentation format, and it has a cost. If you are skimming a file in an editor that does not render emoji well, or you are reading the code on a platform that strips them, you lose the structure that tells you which comments are instructions and which are ordinary notes. The README is the only place that decodes the legend, so it is worth keeping open in a second window while you work. Berry the Bomb is the one to watch: deleting code on purpose is a step, not a mistake, and undoing it by reflex will put you back where you started.

Where this repository is the wrong tool

The most important limitation is that this is not a reusable artifact. package.json is marked private, there are no published releases, and the workshop branches are deliberately incomplete states of the app. If you want a React starter, an npm package, or a reference implementation to copy into a product, this is the wrong repository. The exercise branches exist to be broken and then fixed.

The second limitation is the test suite's authority. The README says outright that the tests are there to help you reach the final version but that a correct implementation done differently from the author's solution can still fail them. That is a deliberate design choice for a workshop, where the tests nudge you toward one path. In a production repository the same property would be a defect.

The third is dependency age and pinning. react-query is fixed at 2.1.1 and react-query-devtools at 2.3.3, with no caret range, while React itself is ^18.2.0 and react-scripts is ^5.0.1. The README also notes the videos were recorded on React ^16.13. Anyone using the repository to learn current React Query patterns should know that the API surface here is the version the workshop was built around, not whatever is current now. There are no releases in the repository, so there is no changelog to consult about how these pins have moved.

Alternatives, and how they differ in approach

The closest alternative is the official React documentation's own tutorial track, which builds a small tic-tac-toe game and then a thinking-in-React walkthrough. The difference in approach is scope and scaffolding: the React docs build a toy from a blank file, while bookshelf ships a full create-react-app project with routing, mocked network calls, a component library, Jest and Cypress already wired up, and moves you between prepared branches. You get far more realistic code to read here, and far less freedom to choose your own stack.

A second alternative is a general-purpose React starter such as a create-react-app template or a Vite scaffold. Those give you a clean, unopinionated project you actually keep. bookshelf gives you an opinionated project with deliberate gaps and a GPL-3.0-only licence. If the goal is to start a product, the scaffold wins. If the goal is to be walked through the decisions behind a real app, the scaffold teaches you nothing, because the decisions have already been made silently.

Maintenance, licence and the upgrade question

The repository is not archived, and its last push was on 2026-03-10. That is roughly six months before today, so it sits right at the edge of what most people would call current. There are no retrieved releases, so there is no version history to reason about and no upgrade path documented in the README. Practically, you consume this repository by cloning it at a point in time and working the exercises, which means the usual upgrade concerns apply mostly to the dependencies you inherit rather than to the workshop itself.

The licence situation needs care. The README badge points at GPL 3.0, and package.json declares "license": "GPL-3.0-only". The repository metadata reports NOASSERTION, which is GitHub declining to classify the licence automatically; the package manifest is the more specific statement here. GPL-3.0-only is a copyleft licence, which is a meaningfully different proposition from the MIT licence most React examples carry. If you copy code out of this repository into something you distribute, the obligations that follow are a question for a lawyer, not for this article. The safe reading is that this is workshop material to learn from, and that lifting it wholesale into a product is a decision with consequences the README does not discuss.

Editorial conclusion

Adopt this repository if you are working through the Epic React Build an Epic React App workshop, or if you want a realistic React 18 codebase with MSW mocks, React Query 2.1.1 and a Jest plus Cypress test setup to read. Do not adopt it as a dependency, a starter template or a production scaffold: it is private, GPL-3.0-only, and its exercise branches are deliberately incomplete. Before you start, verify that git is at v2.13 or greater, Node is >=16 and npm is >=8.16.0, because node setup and the engines field both assume those versions.

Frequently asked questions

Official sources

1. Issues
2. kentcdodds/bookshelf on GitHub
3. Project website
4. README