adamhaile / surplus

High performance JSX web views for S.js applications
638 stars 26 forks source link

Compiler docs #38

Closed rickmed closed 6 years ago

rickmed commented 6 years ago

Could you explain a bit what does the compiler do, why is it needed, etc?

adamhaile commented 6 years ago

Hi Rick -- At a minimum, we need a compiler for the obvious reason that browsers can't run JSX: it needs to be translated to plain JS first. So then there's the question of why can't Surplus use the standard babel-based JSX compiler used by React and other libraries (Preact, Inferno, etc) that use JSX. The reason is two-fold:

  1. The React compilation strategy is optimized for virtual DOM libraries, while Surplus creates real DOM nodes. So, for instance, if you set an attribute in a JSX expression, like <input type="text" />, React will capture the attribute as a property object -- { type: "text" } -- which will then be applied to the real DOM node when the component is rendered. Surplus has the real DOM node from the start, so it generates code that immediately sets the attribute -- element.type = "text".

  2. This gets a bit technical: in order to make the rendered views reactive, Surplus needs to wrap the bodies of the dynamic parts of the view (the stuff in curly braces {...}) with thunks -- () => .... This allows the generated code to evaluate those expressions inside S computations, such that we can capture any signals which are referenced and schedule updates when those signals change. This is a source-level transformation that can't be run once the expressions have been evaluated so must be done at compile time.

Hope that helps. I can explain further if you're interested.

magdute70 commented 6 years ago

So... how to use this compiler without surplus-toys? Any step by step instructions available for novice?

adamhaile commented 6 years ago

https://github.com/adamhaile/surplus#compiler