Understanding the codebase

[bergwerf]

As stated on https://preactjs.com/about/project-goals/, one of the goals of this project is that "Understanding the codebase should take no more than a few hours."

I am looking into the codebase of Preact to answer the following question: Where is the logic that decides when to render/diff which parts of the view?

I would also like to understand the relationship between preact and @preact/signals, and have an idea of how fine-grained signal-based updates really are. Where do I start?

[marvinhagemeister]

The way Preact works is conceptually similar to a typical depth-first tree traversal algorithm. The first render starts of at root node (the one you pass to render()). Renders in the middle of the tree can only ever be triggered by component updates. Those are all kicked off in component.prototype.setState(). Each node in the tree is referred to as a vnode with "v" being for "virtual". VNodes representing components instantiate a component class instance which itself has a pointer back to the vnode. When a subsequent render is called it basically diffs against itself inside setState.

If you're using only the core library itself or the preact/hooks addon, this is all that's needed. There is no need to know which parts to render, because they user calls that themselves. Once a component's setState method is called, it will traverse all of it's children unless a component bails out of rendering by returning the same vnode or by returning false from component.shouldComponentUpdate.

Now signals in comparison do know which parts they need to render and which not to. That works by adding a whole layer above Preact which stores that information. Every signal knows its subscribers and any dependents if available. When a signal is updated it walks through the dependency tree and updates them. Since signals must not have circular dependencies it's again a form of tree traversal, but this time with topological sorting. The update chain is always Signal (source) -> Computed(derived) -> Effect.

The Effect is always at the end of the chain and can call whatever callback you give to it. Now how do we merge the signal update mechanism with Preact's rendering? It's basically a simple trick: We just pass a component's setState method as the callback to Effect. Et voila, we have an update mechanism that only updates the parts that are needed.

Inside the @preact/signals package we went a step further and also made it possible to attach signals to other elements than components like HTML elements or attributes. That's mostly done by hooking into the renderer directly, but that's more of an implementation detail. Conceptually they work the same way as components.

Note that the phrase "Understanding the codebase should take no more than a few hours." is about the core library, not about understanding the whole ecosystem together like with signals, etc.

[bergwerf]

Thank you for your reply! So the components setState method is the beginning of all updates, and components are a more generic concept than just HTML elements? In the hooks code I found a global variable called currentComponent, which appears to be the trick to connect useState to a component.

There are two other questions on my mind:

1. When a signal x is used in the render method of some component (resulting in a call to x.value), how does it end up receiving the setState of the parent component? Is there some magic in the JSX compilation? Is the render call executed by Preact in such a way that it can list all the signal value calls? (and then subscribe to them until the next render)

2. You mention that HTML attributes can also be components (which I assume can be updated independently). When I make a (let's say functional) component containing an HTML element with a class attribute that depends on the signal x, for example <p class={x.value == 1 ? 'one' : 'not-one'}>Hello, World!</p>, then does the class attribute become a component in itself? Or when x changes is the whole element rendered (and diffed) again?

[marvinhagemeister]

Yes exactly, the hooks addon attaches some callbacks to the renderer via the option.* interface. These allow you to plug into the renderer and be notified when two vnode's are diffed, when they render, when a node completed diffing and other hooks. Through that the addon can keep track of the currently rendering component and gain access to its setState method.

1. The exact same technique as for hooks is used for signals. They keep track of the currently rendering component and store that in a currentComponent variable too. And just before we render, we create an Effect signal and set it's update method to that setState method of the currently rendering component. The signals you access don't trigger the component update directly. It appears that way and that's what makes the API so nice for and end user. What's actually happening is that a signal accessed inside a component subscribes to the currently active Effect signal, which happens to be the one we just created before calling the component function. And that in turn has access to the component's setState method.

It's this architecture which allows us to keep the renderer completely free from any knowledge of how the update was triggered. From its point of view it's merely the standard setState update flow.

2. No, the signal in your example doesn't update the attribute, it subscribes to the component.

function App() {
  return <p class={signal.value == 1 ? 'one' : 'not-one'}>Hello, World!</p>
}

has the exact same semantics as:

function App() {
  const value = signal.value == 1 ? 'one' : 'not-one';
  return <p class={value}>Hello, World!</p>
}

The signal is unwrapped way early inside the scope of the currently rendering component, so it will subscribe to the currently active Effect that we just created before rendering the component, which again in turn holds a reference to the components setState method.

But passing the signal directly as the attribute value allows the renderer to set up the subscription, just as it's applying the updates to the HTML element. This means the signal must not be unwrapped any earlier.

function App() {
  return <p class={signal}>Hello, World!</p>
}

Just before we render an HTML vnode, we check if any of its props is a signal. If it is, then we do pretty much the same thing as we do for components. We'll create an Effect but instead of binding it to setState of the outer component, we bind it to a function that directly sets attribute on the HTML element. We basically bypass Preact's normal rendering here completely. So that sense all attributes of the element are rendered again. We had a version where we could bind to single attributes, but that proved to be slower and way more memory intensive as we needed to track and create separate Effect signals for every attribute. Was much faster to just use one for all attributes of an element.

Of note here is that the element doesn't become a component internally. That only happens when you pass a signal as a text child. Another thing to be aware of is that all this requires zero compilation help. It's all standard JS code and other than the bog standard JSX transform, not compilation is happening at all.

[bergwerf]

Thank you for the clarification! I guess the setState Effect you mention is somewhere here: https://github.com/preactjs/signals/blob/60dae3f060ca72abdeb6f56d2c5b23a08c01a4f8/packages/preact/src/index.ts#L147 (although there are several things going on that probably require more in-depth knowledge of the library).

So this:

function App() {
  return <p class={computed(() => signal.value == 1 ? 'one' : 'not-one')}>Hello, World!</p>
}

will make sure only the attributes of <p> are updated when signal is updated, right?

[marvinhagemeister]

Yup, that's the exact place.

The snippet is close. Because a component will rerender all the time the computed call would always re-create a new signal on each render.

function App() {
  // The hook variant ensures that the same signal is returned
  const value = useComputed(() => signal.value == 1 ? "one" : "not-one"));
  return <p class={value}>Hello, world!</p>
}