# browserengineering/book ships a browser you build one chapter at a time

> Web Browser Engineering is an open book on how browsers work, and the interesting part is that the code for every chapter is in the repository as a runnable Python browser. It suits readers who want to understand rendering, layout and JavaScript execution by reading and running the thing, and the book is free to read online.

**browserengineering/book** — Web browser engineering (a book)

- Repository: https://github.com/browserengineering/book
- Website: https://browser.engineering/
- Stars: 1,174 · Forks: 105
- Language: JavaScript
- License: MIT
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/browserengineering-book

## The book is a repository, and the repository is a browser

browserengineering/book holds the source for Web Browser Engineering, a book on how web browsers work. The README calls it the source code to the book and points readers to the online version as the best way to read it, hosted at browser.engineering. The licence is MIT and the last push was on 2026-09-27, so the text and the code are both maintained in the open.

What makes this different from a normal book repository is the src directory. The README states that code for the browser developed in the book can be found in src, in files named lab1.py, lab2.py and so on, corresponding to each chapter. You are not reading about a browser. You are running one, in a state that matches where the chapter left off, and reading the source that produced it.

That structure changes what the repository is for. A prose book about browser internals tells you that layout is a box tree; this one hands you a file where the box tree is computed, at the exact point in the narrative where the argument for that algorithm is being made. The audience is people who learn systems by reading and running them, and educators, whom the README explicitly invites to get in touch about using the book in a course.

## One lab file per chapter, and the browser grows as the chapters do

The lab files are cumulative. The README gives the example of running the browser as of the end of Chapter 3:

```bash
cd src/
python3 lab3.py https://browser.engineering
```

Every chapter can be run in a similar fashion, which means the lab file for any chapter is a complete, runnable browser at that point in the book's progression. That is the pedagogical mechanism. A chapter on text layout does not ask you to imagine layout on top of an abstract renderer; it asks you to run the file that has the network layer, the DOM parser and the previous chapters' box algorithm, and change one thing.

There is a second thread in the same directory. From chapter 8 onward there is also a guest book web application, run with server8.py, and like the browser there are different versions of the server for different chapters, named server8.py, server9.py and so on. The server exists so the later chapters have a real origin to talk to: same-origin policy, forms, scripts and security are far easier to demonstrate against an application you control than against a public site.

The Makefile reflects the same structure at the book level. The widgets target lists lab1.js through lab16.js and the per-chapter server scripts, and the chapters variable names the full table of contents in order, from preface, about, intro and history through http, graphics and text, then html, layout, styles and chrome, then forms, scripts and security, then visual-effects, scheduling, animations, accessibility, embeds and invalidation, and finally skipped, change, glossary, bibliography, classes and porting.

## Dependencies climb chapter by chapter, and the README tells you when

Running the labs needs a Python installation and the tkinter package, which is part of the Python standard library but often is not included in pre-installed Pythons on macOS and Linux. The README suggests checking with python3 -m tkinter, which should open a test window. A recent Python 3 is required, and version 3.9.10 is known to work, with older versions probably working too.

After that, the dependency list grows with the chapters, and the README is specific about which chapter needs what. For Chapter 9 and later you need the dukpy package, for executing JavaScript. For Chapter 11 and later you need the skia and pysdl2 packages, for advanced graphics and a Skia-compatible GUI. The requirements file pins the versions: dukpy 0.5.0, skia-python 144.0.post1 with pybind11 3.0.1, PySDL2 0.9.17 with pysdl2-dll 2.32.0, and PyOpenGL 3.1.10, which the file attributes to chapters 13 and later for GPU-accelerated Skia.

That structure is a deliberate teaching device as much as a practical one. A reader working through the book in order installs the extra packages exactly when the chapter that needs them arrives, so the dependency list is part of the narrative rather than a wall at the start.

## Building the book requires a make target and a Python toolchain

The book itself is built from source with a single command:

```bash
make book draft blog
```

The make targets reflect how the project is put together. The book target depends on the rendered chapter HTML, an RSS feed, the widgets, the examples and the index and one-page versions, and the widgets target generates the per-chapter browser and server scripts that the online text embeds. The examples target processes the example HTML, JavaScript and CSS files in src into their published form.

The source layout is separated by concern, which is worth noting if you want to reuse any part of it. The Markdown source for the book text is in book/, a template and the code for converting the book to HTML are in infra/, the chapter-by-chapter browser implementations are in src/, the styling for the book's website is in www/, and the Python backend for the former feedback system lives in www/ and infra/ as well. The repository also holds book-edited.tex and a latex directory, which suggests a LaTeX path to a printed edition, along with config.json, news.yaml and requirements.txt.

The book's built-in feedback system is disabled. The README asks readers to open a GitHub issue for typos and small comments about the text, which is a smaller ask than a working feedback server would be.

## lint and test are the two checks a contributor can actually run

Two make targets matter for anyone working in the repository. make lint runs the book's built-in checks, and make test runs the book's unit tests. There is also a .coveragerc at the root, so the test run is set up for coverage measurement rather than being a bare pass or fail.

The quiz JavaScript is the one part of the site that is built from another project's source. The source for the interactive multiple-choice quizzes is taken from mdbook-quiz, and rebuilding the JS blob included on the quiz pages, in www/quiz-embed.iife.js, needs a specific toolchain: depot installed with cargo install depot-js --locked, cargo-make, a clone of the mdbook-quiz repository, then cargo make init-bindings, a move into the js directory, and depot build. The output is expected at packages/quiz-embed/dist/.

The README credits these steps to the README.md and CONTRIBUTING.md files of the mdbook-quiz project, which tells you where the authoritative instructions live. This is a small corner of the build, and it is the one part where the source of truth is in a different repository.

## A browser engine is the wrong tool for most product work

It is worth being clear about what this is not. The lab files are teaching implementations. They grow one feature at a time, they are written in a style that makes the algorithm legible, and they exist to be read alongside prose that argues for that algorithm. A team shipping a product would not deploy them, and the repository makes no claim otherwise.

There is a second boundary. The implementations are Python, and a browser is largely specified in terms of behaviour that a Python process only partially reproduces. The dependency on tkinter for the early chapters, dukpy for JavaScript execution from chapter 9, and skia with pysdl2 for graphics from chapter 11 shows the shift from a simple text renderer to a real graphics stack, and each of those transitions comes with an installation step the reader has to complete. The book's own dependencies are the honest measure of how far the implementation goes: no GPU work until chapter 13, no native browser embedding, no devtools protocol, no site isolation model.

The right comparison is not with Blink or WebKit. It is with a well-structured lecture course: the value is in the sequence of ideas and the runnable artefact attached to each one, not in a production-grade engine you could point a crawler at.

The README also says the book is free to read online, and that readers and educators are welcome to write in. The licence on the repository is MIT, which covers both the prose and the code; reuse still requires keeping the copyright notice.

## Conclusion

browserengineering/book fits engineers and students who want an operational understanding of browser internals rather than a survey, and it does not fit teams looking for a production browser engine or for language-agnostic reference documentation. Before working through it, install the chapter dependencies the README lists, since later chapters need dukpy for JavaScript execution and skia plus pysdl2 for graphics, and start with the source directory where lab1.py onward correspond to each chapter, then run the browser as of Chapter 3 against a page you control.

## FAQ

### How do I run the browser code from Web Browser Engineering?

The chapter implementations live in src as lab1.py, lab2.py and onward. Change into src and run the file for the chapter you want, for example python3 lab3.py https://browser.engineering, and every chapter follows the same pattern.

### What do I need to install to run the labs?

A recent Python 3, the tkinter package from the standard library, and for later chapters dukpy from chapter 9 and skia plus pysdl2 from chapter 11. The requirements file pins dukpy 0.5.0, skia-python 144.0.post1, PySDL2 0.9.17 and PyOpenGL 3.1.10.

### How do I build the book from source?

Run make book draft blog, and use make lint for the built-in checks and make test for the unit tests. The quiz JavaScript in www/quiz-embed.iife.js is a separate build that needs depot, cargo-make and a clone of the mdbook-quiz project.

### Is the Web Browser Engineering book free to read?

The README states that the best way to read the book is online at browser.engineering. The repository is licensed under the MIT licence, and the book asks readers and educators to get in touch about using it.

## Sources

- [browserengineering/book on GitHub](https://github.com/browserengineering/book)
- [Issues](https://github.com/browserengineering/book/issues)
- [License: MIT](https://github.com/browserengineering/book/blob/main/LICENSE)
- [Project website](https://browser.engineering/)
- [README](https://github.com/browserengineering/book/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/browserengineering-book