chibivue rebuilds Vue.js in readable TypeScript, one layer at a time

A Vue.js reimplementation written to be read

chibivue is a minimal implementation of Vue.js built for educational purposes, and it comes with an online book that walks the reader from a single Hello, World line up to a working framework. The name comes from the Japanese word for small, and the ambition is deliberately scaled down: enough of the real architecture to understand it, without the accumulated complexity of a production codebase.

The feature set listed in the README covers the core subsystems of a modern framework: a reactivity system, a virtual DOM with patch rendering, a component system, a template compiler, an SFC compiler, and a vapor mode that is marked as experimental. The repository description goes further and names SSR, a store, a router and language tools as well.

The audience is explicit in the README title line, which frames the project as writing Vue.js step by step from one line of Hello, World. That framing sets expectations about what you get. Every chapter exists to make one mechanism legible, so the code is written for reading rather than for performance, and the trade-off is that none of it should be shipped as your application framework.

The project is written in TypeScript, and the type definitions, the compiler tooling and the tests are part of the repository rather than something bolted on afterwards.

The book and the implementations live side by side

The repository layout makes the pairing explicit. There is a book directory that holds the online book sources, including an online-book folder with its own public assets, and an impl directory for the implementations the book teaches. The examples directory contains an app and a vapor example, which is how the reader sees the finished pieces running outside the tutorial sandbox.

The book is published in four languages, with the English version at the root of the site, plus Japanese, Simplified Chinese and Traditional Chinese paths. It is deployed by a GitHub Actions workflow, and the README links a Discord server for discussion.

Because each chapter is paired with working code in the same repository, the reader can open the file the chapter is talking about and read it side by side with the prose. That is the central design choice of the project, and it explains the repository shape: rules, tools, textlint configuration and a .textlintignore at the root suggest the prose is linted in the same way the code is checked.

For a reader who wants to skim rather than build, the bonus chapter offers a condensed version of the same ideas, which is the fastest way to decide whether the book is worth working through.

Reading the book locally with Vite+ and pnpm

The quick start assumes Vite+ is available on the command line as vp. Node.js and pnpm are then managed by Vite+ itself through vp env, using the versions pinned in package.json, so a contributor does not have to install a specific Node version by hand. The README lists Node.js v26 and pnpm v12 as those pinned versions.

Cloning and running the book locally takes four commands:

git clone https://github.com/chibivue-land/chibivue
cd chibivue
vp install
vp run dev

vp install resolves the workspace dependencies, and vp run dev starts the development server for the book site, which is the same site published at book.chibivue.land.

The workspace is pnpm based. The repository root carries pnpm-workspace.yaml and pnpm-lock.yaml, and package.json pins [email protected] as the package manager and declares a node engine requirement of >=26. A devEngines block asks for Node.js 26.11.1 with an onFail of download, so the tool can fetch a matching runtime instead of failing the install:

  "engines": {
    "node": ">=26"
  },
  "packageManager": "[email protected]"

That floor is worth noting. A machine with an older Node.js installed will not run the book without upgrading or letting the tool download a matching runtime.

Generating the playground and starting an implementation

The second quick start block covers the code rather than the prose. The README calls it trying the implementation, and it uses two task scripts:

vp run setup     # Generate playground
vp run impl:dev  # Start dev server

The setup task generates the playground, which is the scratch environment the chapters work inside. The second task starts the development server for the implementation. The order matters, since the playground is what the implementation is developed against.

The dependency list explains why the playground needs its own machinery. Alongside the compiler and bundler packages sit @monaco-editor/loader and monaco-editor, so the playground can show a code editor with syntax highlighting, and @webcontainer/api, which runs code in the browser through WebContainers. estree-walker and magic-string are the usual companions of an AST-based compiler, walking the parsed tree and rewriting source text.

Vapor mode has its own example directory, examples/vapor, separate from examples/app, which is a good sign for how the experimental renderer is meant to be tried: as a distinct app rather than a switch hidden in the main one.

The 110 line version as a sanity check on your understanding

The bonus track, titled Hyper Ultimate Super Extreme Minimal Vue, implements createApp, a virtual DOM, reactivity, the template compiler and the SFC compiler in what the README states as 110 lines. The source sits at book/impls/bonus/hyper-ultimate-super-extreme-minimal-vue/packages/index.ts, and the chapter links to both the prose and that file.

The purpose is pedagogical rather than competitive. Read after the main chapters, that single file is a check on whether the reader can hold the whole mechanism in their head at once. Every abstraction the longer implementations build is collapsed into one module, so the essential data flow between template compilation, reactive state and DOM patching is visible without intermediate layers.

It is also a useful way to decide whether the book suits you before committing to it. If the 110 line version reads as comprehensible, the full chapters will too. If it reads as a wall, the book may be denser than you want right now.

One caveat to keep in mind while reading: this is a teaching implementation, so the code is optimised for legibility. Treat any performance characteristic as a property of the exercise, not of Vue.js.

The toolchain is heavier than the framework it teaches

The dependency list in package.json is worth reading as a description of what a modern frontend project drags in, because chibivue's own build needs most of the same tools as a real application. Alongside vite, vite-plus and @vitejs/plugin-vue, the development dependencies include typescript, vitest, jsdom, playwright and @vitest/browser-playwright, which together provide type checking, unit tests and browser based tests.

There is also a linting and minification stack: oxc-minify for output, eslint is absent but the repository does carry textlint with textlint-rule-ja-space-between-half-and-full-width and textlint-rule-prh, which are Japanese prose rules. That combination tells you the book text is checked by the same workflow as the code, with a Japanese line breaking rule and a term harmonisation rule applied to the text.

Two entries stand out for anyone copying the setup. @vitejs/plugin-vue and vue itself are present as development dependencies, so the real Vue.js is available for comparison inside the same workspace, alongside the hand-written implementations.

The catalogue references such as "catalog:" in the dependency list mean versions are resolved through a shared catalogue rather than pinned per package, which keeps a multi-package workspace consistent when one version is bumped.

Releases track the book, and the licence is permissive

The project is not archived and the last push was on 2026-10-19, so work is ongoing and recent. Releases are versioned in step with the book: v1.0.0 on 2026-03-12, v1.1.0 on 2026-04-11 and v1.2.0 on 2026-10-13. The version in package.json is 1.2.0, matching the newest tag.

The MIT licence recorded in package.json and in the LICENSE file at the repository root is about as permissive as it gets. You may use, copy, modify and redistribute the code, including inside commercial and closed-source products, and the only obligation is to keep the copyright notice and licence text. That is a licence fact rather than legal advice, and the practical point for readers is that the implementations and the book text can be reused in your own lessons without asking for permission.

One consequence of the book being the product is worth flagging for teams. The repository is a documentation project with code attached, so version numbers track the prose. If you depend on a particular implementation file, check it against the tag you are reading rather than assuming the branch tip matches the published chapter.

Contributions are handled through .github/contributing.md, and the repository carries a CODEOWNERS file, so ownership of each area is recorded.

Where chibivue stops and Vue.js itself begins

The clearest limit is scope. This is a teaching implementation, and its features are intentionally partial: the README marks vapor mode as experimental, and the feature list stops at the compiler level with no mention of production concerns such as hydration for SSR, error handling conventions, devtools integration, tree shaking or bundle size. The repository description names SSR, a store, a router and language tools, but the README does not document how complete each of those is, so treat that line as a roadmap rather than a specification.

The alternative is the original. If your goal is to know how Vue.js behaves today, the authoritative source is the vuejs/core codebase and its own documentation, and chibivue can mislead you precisely because it is simplified: it drops the branches that production code accumulates over years. The value is the opposite of fidelity. chibivue shows one clear path through the mechanism, where the real source shows every historical accommodation.

There is a second choice worth making explicitly. If you only want to understand the core data flow, the 110 line bonus implementation is a lighter dependency than the full workspace, with no playground, no Monaco editor and no WebContainer runtime. The full monorepo earns its weight when you want the guided chapters and the sandbox.

Finally, this is not a replacement for Vue.js in production. Choosing it for a shipping product would mean giving up the ecosystem, the tooling and the battle-tested edge cases, in exchange for readability you only need while learning.

Editorial conclusion

chibivue suits developers who want to understand how a modern frontend framework is put together, and who read better in a guided sequence than in a large production codebase. It is the wrong choice as a runtime dependency, as a Vue replacement for a shipping product, or as a source of Vue's current behaviour, since the implementations are deliberately minimal. Before you start, check the chapter list in the online book at book.chibivue.land against the topics you want covered, and note that the project requires Node.js 26 with pnpm 12, which is a higher toolchain floor than most Vue projects today.

Frequently asked questions

Official sources

1. chibivue-land/chibivue on GitHub
2. License: MIT
3. Project website
4. README
5. Releases