nixos-and-flakes-book: a February 2024 disclaimer on a book at v0.9.0, and a check script with no tools

A warning section that ends by telling you to set it aside

The section on Flakes opens with the case for them: better reproducibility, composability and usability, widely used by the community, and one of the most significant changes the Nix project has seen. Then the caution. Flakes is described as still an experimental feature, some issues persist, breaking changes may arrive during the stabilization process, and the extent of those changes remains uncertain. The paragraph after that recommends that everyone use Flakes anyway, on the grounds that the book itself is built around NixOS and Flakes. So the caution contains no action: there is no list of known problems to check, no version to avoid, no alternative to configure instead. The claim that more than half of users rely on Flakes is footnoted to a draft one-year roadmap from the NixOS Foundation, reached through an archived snapshot of that page dated 2025-03-17, so the number behind the reassurance is a draft document in an archive.

The author's disclaimer is stamped February 2024

The feedback section opens by saying the author is not an expert on NixOS and has been using it for less than nine months, and it dates that claim in parentheses as 2024-02. The current release is v0.9.0, tagged on 2026-10-03, with v0.8.2 published the same afternoon and v0.8.1 in August 2026, and the last commit on main is dated 2026-10-03. So the statement of qualifications is close to three years older than the artifact it qualifies, and it has not been restated. The book labels itself an unofficial and opinionated NixOS and Flakes book for beginners, and the reason given for writing it is that nobody in the community had done it for the author when they were a beginner. That framing is unusually candid, and it is also the framing to hold the examples to: mistakes are expected, and the correction path is an issue or a pull request with reasoning.

Five languages, two build targets

The README separates author-maintained versions from community-maintained ones. English and Chinese live on the same site under different paths, and the other three are hosted on three unrelated domains: a Portuguese version on ieda.me, a Japanese version on hayao0819.com and a Spanish version on voros.xyz. The build side covers only the first two. The combined export script runs four jobs in sequence, a PDF and an EPUB for English and a PDF and an EPUB for Chinese, driven by a `--lang` flag on two underlying scripts, `export-pdf` and `export-epub`, both run through tsx. So the downloadable formats follow the author's own translations and not the community ones. That split also shows up in the dependencies, where `markdown-it-cjk-breaks` is present specifically to handle line breaking in the Chinese text.

The check script calls two tools the manifest never declares

The quality gate is one line: `prettier --check .` followed by `typos .`, chained so the second only runs if the first passes. The devDependencies list holds two packages, tsx and vitepress. Neither prettier nor typos appears in devDependencies or dependencies, and neither is present as a transitive guarantee of anything else in the list. The repository does commit a `.prettierrc.yaml` and a `.prettierignore`, so prettier is definitely meant to be used, and `typos` is being run as a spell checker over the whole tree, which for a book with mixed English, Chinese and command output is a setting that needs configuring. Two tools assumed to be on the developer's machine, in other words, and a config for one of them committed while the tool is not.

PDF and EPUB exports with no export library listed

Both export scripts run under tsx, which is declared, so the entry point is available. What the manifest does not contain is anything that produces a PDF or an EPUB: no PDF library, no EPUB generator, no headless browser in the dependency list. The dependencies that are declared are markdown-it-cjk-breaks, markdown-it-footnote, sitemap-ts and a VitePress plugin for comments through Giscus. Two of those have a clear purpose in the book itself, the CJK line breaking and the footnote support that the README's own numbered references depend on, and the sitemap is for the site. So the export scripts either do the work themselves, reach for a tool outside the manifest, or rely on something the package file does not say. Anyone rebuilding the book from a clean clone will find that out at export time rather than at install time.

A book about flakes ships a flake

The root holds `flake.nix` and `flake.lock`, so the tooling of the book is itself managed by the tool it teaches, which is a reasonable statement of faith and also means the book has a build dependency most readers will not have. Alongside it sit `pnpm-lock.yaml`, `pnpm-workspace.yaml` and a `.npmrc`, with the package manager pinned in the manifest as `[email protected]` rather than left to a version file, and `vercel.json` for deployment. The docs themselves live under `docs/`, with `docs:dev`, `docs:build` and `docs:preview` scripts pointing VitePress at that directory. One small oddity: the root manifest declares a type, a package manager, scripts and dependencies, but no name and no version field, which is normal for a workspace root and worth knowing before anything tries to publish it.

macOS readers are pointed at another repository

The book covers NixOS, and for anyone on macOS the README suggests a different repository, nix-darwin-kickstarter, as a starting point, with the suggestion that you learn Nix here and use that project to build your own configuration. That is an honest boundary: the book itself assumes a NixOS system, and the macOS path is somebody else's project. Feedback has two routes, an issue or the GitHub Discussions page, and the site's comment feature goes through Giscus, which is GitHub Discussions rendered on the page, so the two are the same channel. The contribution section asks for pull requests with valid and well-reasoned explanations and points at the contributing guidelines in `.github/`, and `AGENTS.md` sits at the root beside them, which is where automated tooling instructions for the repository would live.

Editorial conclusion

This book fits a reader who wants one opinionated path through NixOS and Flakes rather than the manual, and who will read it start to finish rather than dip into it for a single command, since the author explicitly describes it as unofficial and opinionated and invites corrections through issues and pull requests. Three things to know first. The caution about Flakes being experimental is real and unresolved, and the same section recommends using it anyway, so treat the book as a workflow opinion rather than a stable reference. The author's own statement of experience is pinned to February 2024 and has not been revisited in three years of releases. And the tooling is lighter than it looks: the quality check runs two binaries the manifest does not declare, and the PDF and EPUB exports go through two scripts with no export library in the dependency list, so if you want to build the book yourself, expect to supply those tools yourself.

Frequently asked questions

Official sources

1. License: CC-BY-SA-4.0
2. Project website
3. README
4. Releases
5. ryan4yin/nixos-and-flakes-book on GitHub