Core Concepts in a Nutshell¶

Data Structures

Create Store objects to keep track of simple state variables, and keep them in sync with the frontend.
Create DataFrame objects to keep track of complex, data state.
Think of Store objects as “by-value”, in that their raw value is sent to the frontend.
Stores behave like the values they wrap, so you can pretend the Store is just its value (with one exception: use Store.value inside @endpoint functions for clarity).
Think of DataFrame objects as “by-reference”, in that a reference to the data is sent to the frontend, and the frontend can request the data when it needs it.

Reacting to Changes

Use the @reactive decorator to register a function as reactive.
Use reactive functions inside the with react() context manager. The function will be called whenever any of its arguments change.
Use reactive functions as normal Python functions without the with react() context manager, or inside a with no_react() context manager.
Think of reactive functions as a way to create views of data. Use them to return new Store and DataFrame objects, than can then be visualized.
Chain reactive functions by consuming the output of one as the input to another, in order to create complex reactive applications.
Put simple Python statements over Store objects inside with react() in order to make them reactive.

Creating Endpoints

Use the @endpoint decorator to register a function fn as an endpoint, returning an Endpoint object.
Use fn.partial(…) to create a new Endpoint object that fills in some of the arguments of fn.
Use fn.run(…) to run fn with the given arguments.
Pass Endpoint objects to on_xxx Component attributes, in order to call the endpoint when an event occurs.

Data Manipulation

Manipulate Store and DataFrame objects inside @endpoint functions, and use the .set() method to update them.
Do not manipulate these objects inside @reactive functions, as this will cause an infinite loop.

Attaching Components

Initialize any of the available Components by passing in Store, DataFrame and Endpoint, alongside other arguments.
Think of Components as a way to manipulate and visualize data.
Manipulate Store objects directly on the frontend via user input.
Manipulate Store and DataFrame objects by dispatching to an Endpoint.
Build your own Component objects by writing a single Svelte file per component.

Gotchas

Using Python primitives instead of Store objects, and expecting them to be in sync with the frontend.