# nixos-and-flakes-book: a February 2024 disclaimer on a book at v0.9.0, and a check script with no tools > An unofficial, opinionated book about NixOS and Flakes for beginners, published as a VitePress site in English and Chinese with community translations in three more languages. Its warning section tells you to expect breaking changes and then recommends ignoring them, its author's disclaimer is dated February 2024, and its check script invokes two command line tools the manifest never declares. **ryan4yin/nixos-and-flakes-book** — Want to know NixOS and Flakes in detail? Looking for a beginner-friendly tutorial? Then you've come to the right place! - Repository: https://github.com/ryan4yin/nixos-and-flakes-book - Website: https://nixos-and-flakes.thiscute.world - Stars: 3,325 · Forks: 158 - Language: TypeScript - License: CC-BY-SA-4.0 - Published: 2026-09-24 · Updated: 2026-09-24 · Language: en - Canonical page: https://hysenlabs.com/projects/ryan4yin-nixos-and-flakes-book ## 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 `pnpm@11.4.0` 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. ## 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. ## FAQ ### What is nixos-and-flakes-book? An unofficial and opinionated book about NixOS and Flakes aimed at beginners, published as a VitePress site with author-maintained English and Chinese versions and community versions in Portuguese, Japanese and Spanish. It is licensed CC BY-SA 4.0, and the author says they wrote it because nobody else had, describing themselves as not an expert who had used NixOS for under nine months as of February 2024. ### Are Nix flakes still experimental? According to the book, yes. A dedicated section says Flakes is still an experimental feature, that some issues persist, and that breaking changes may be introduced during stabilization with the extent uncertain. The same section then recommends using Flakes anyway, since the book is built around them. ### Is nixos-and-flakes-book available as a PDF or EPUB? Yes, through two export scripts, `export-pdf` and `export-epub`, both run with tsx and both taking a `--lang` flag. The combined `export` script runs all four combinations, but only for English and Chinese, which are the two author-maintained versions; the three community translations are not part of it. ### Which languages is nixos-and-flakes-book available in? English and Chinese, both maintained by the author, plus community-maintained Portuguese, Japanese and Spanish versions hosted on three separate domains. The build and the export scripts cover only the first two languages. ### What checks run on the nixos-and-flakes-book repository? One script: `prettier --check .` followed by `typos .`. Neither prettier nor typos appears in devDependencies, which list only tsx and vitepress, even though a `.prettierrc.yaml` and a `.prettierignore` are committed at the root. ## Sources - [License: CC-BY-SA-4.0](https://github.com/ryan4yin/nixos-and-flakes-book/blob/main/LICENSE) - [Project website](https://nixos-and-flakes.thiscute.world) - [README](https://github.com/ryan4yin/nixos-and-flakes-book/blob/main/README.md) - [Releases](https://github.com/ryan4yin/nixos-and-flakes-book/releases) - [ryan4yin/nixos-and-flakes-book on GitHub](https://github.com/ryan4yin/nixos-and-flakes-book) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ryan4yin-nixos-and-flakes-book