Help Understanding the Preact Codebase and Dev Workflow

[thamizh-root]

Hey, hi!

I've reached out to a few people but haven’t received any replies. I thought this would be my last resort to ask for help.

Here’s my question in simple terms: How do I understand the Preact codebase?

To elaborate:

I’ve found the source files for core methods like render, diff, and the hooks implementation. I get where the logic lives. But I’m struggling to understand how you all actually develop and debug the library during development.

My plan was to:

• Run yarn run dev
• Add console.log statements to internal functions like render, diff, or toChildArray
• Create an index.html file in the root and load the dev bundle to see those logs in action

However, that didn’t work — I ran into CORS issues, and couldn’t figure out how to correctly map the output to index.html. I explored the debug/ and benchmark/app/ folders but still couldn’t understand how to wire everything up for local debugging.

I also tried a similar approach with the React codebase — no luck there either.

What really sparked my curiosity is seeing how Preact internally reuses logic — like implementing useState on top of useReducer, and other elegant patterns. I want to study and explore how Preact is built the same way I learned Redux — through [Dan Abramov’s famous Redux-from-scratch gist](https://gist.github.com/gaearon/ffd88b0e4f00b22c3159).
2. Is there a minimal setup to load an index.html and test changes interactively in the browser?
3. How do contributors and maintainers usually test their changes — via the test suite, example apps, or something else?
4. Where to start if i wanna learn the internals and understand the codebase?

I’m eager to learn and dig deep into the internals of Preact. Any help or direction would mean a lot!

Thanks so much for maintaining such a great library.

[JoviDeCroock]

There are two ways to work in this repository, you have the demo/ folder which you can run npm i && npm run dev in. This will contain a live copy of the files within the repo so any console.log will show up. This is tested in browser etc as described in point 2.

Secondly you can develop through tests, in every repository you can just look at package.json.scripts to find out what commands you can run. npm run test:vitest is one of ours.

I personally debug libraries with demo/ and solve Preact specific issues with tests running, I write a new test and solve the issue.

4. Where to start if i wanna learn the internals and understand the codebase?

it's a small code base, starting from the start is all you need I reckon, start from render and follow the path. Next up look at setState etc. I sometimes write blog posts about internals like our diffing algorithm, which can be found here https://jovidecroock.com/blog/skew-based-diffing and how extensability works for i.e. hooks right here https://marvinh.dev/blog/preact-options/

I don't know where you reached out but I didn't see anything, feel free to reach out to me on our slack.

[thamizh-root]

Thanks a lot!!! @JoviDeCroock
npm i && npm run dev works — I can now see the console.logs in real time.
I was smashing my head against the wall for the last two days...

I'll come back with an article like “Walkthrough: Building Your Own Preact” after I understand the concepts well.
Hopefully, it’ll be helpful for people like me who want to dive into this goldmine!

[JoviDeCroock]

This might help you as well https://www.puruvj.dev/blog/deep-dive-into-preact-source-code

[thamizh-root]

I tried adding console.log at the start of the diff method and faced two issues:

1. Cloning: The console doesn't display the console.log data in real-time within the cloned repository. How do you manage to view this data? I even wrote an article about this issue: https://watermark.hashnode.dev/debugging-react-internals-why-i-started-cloning-functions-and-objects-seriously. However, I can't use that approach here, meaning I cannot install Lodash in the cloned Preact repository. I'm wondering how you've solved this.
2. console.log Behavior: When adding console.log, I observed something weird: the diff function was called multiple times. My understanding is that diff is only called once after a render. How come it's being called repeatedly? I've observed this behavior in both the performance monitor and through console.log. Can you please explain how and why diff is called multiple times?

[JoviDeCroock]

1. {...yourData}
2. diff is recursive as you can see because it traverses children and diffs them

[thamizh-root]

Now I can apply multiple console.logs everywhere and have gotten some basic ideas... feels great...

I added console.log before and after the diff method in index.js. I noticed the recursive process. My question is: only when recursion is closing down do _children start to get values? What is the difference between children in the props and _children? Obviously, there are many properties similar to React, like flag, type, and so on. Where can I find the meaning of those?

[marvinhagemeister]

You can find information about _children in the same named children.js file. In Particular this line and what follows after that.

preact/src/diff/children.js

Line 171 in b52475b

newParentVNode._children = new Array(newChildrenLength);

The children passed via props are normalized like converting non-renderable children like booleans or null to null, creating text vnodes out of strings, etc. In scenarios where the same vnode is used twice we also need to clone the vnode. The result of all of that is stored in _children.

[thamizh-root]

@marvinhagemeister @JoviDeCroock Honestly, I don't know how you all understood the codebase. Will this version (https://github.com/preactjs/preact/tree/1.3.0) help us understand version 10?

[JoviDeCroock]

No, when you try to understand a codebase it's best to consider a major version in isolation. Conceptually they will match but the implemented concepts will hugely differ. When you approach a codebase it's best to approach it principles first, i.e. what are we trying to do, we are creating a virtual ui representation and reflecting that to the DOM. That similar to updates,...

In that world of creating a virtual representation we need to construct the tree depth first, when we hit a leaf we trampoline back up while comitting that subtree and move on to the sibling when one of those upper levels has siblings.

[thamizh-root]

useful for objects. but spread operators are not helpful to view DOM elements, right? correct me if i'm wrong.

[JoviDeCroock]

Can you reply in the thread rather than in new messages every time please, also you can use console.dir on DOM elements

[thamizh-root]

sure. let me check.