repos / starfx

learn.md

  1---
  2title: Learn
  3description: Fundamental concepts in starfx
  4---
  5
  6# How does `starfx` work?
  7
  8`starfx` is a companion framework to `react` that understands how to listen to
  9user events (e.g. clicks, form inputs, etc.), activate side-effects (e.g. fetch
 10api data, submit form data, update state), and then intelligently update the
 11view. If you are familiar with **MVC**:
 12
 13- `react` is the **View** layer
 14- `starfx` are the **Model** and **Controller** layers
 15
 16The high-level picture of `starfx` is _essentially_ a glorified pubsub system:
 17
 18- The user goes to your app
 19- The view is generated with `react`
 20- When a user interacts with your web app, events gets dispatched
 21- `starfx` listens for events and triggers side-effects (e.g. fetches API data,
 22  updates state, etc.)
 23- An entirely new version of the state gets created
 24- `react` surgically updates the view based on changes to the `starfx` state
 25- Rinse and repeat
 26
 27It all happens as a single unidirectional loop.
 28
 29# How is `starfx` different?
 30
 31`starfx` is different in a number of ways.
 32
 33We combine both state and side-effect management into a single cohesive unit.
 34This streamlines the implementation of your web app.
 35
 36Our business logic does not live inside of `react`, rather, it lives inside of
 37the side-effect system. We are not shackled by `react` lifecycle hooks, in fact,
 38`starfx` has virtually no concept of `react` at all -- except for a couple of
 39hooks. The entire system is designed, from the ground up, to not need `react` at
 40all in order to function. At the end of the day, `starfx` works by subscribing
 41to and publishing events. Those events could come from `react`, but they could
 42also come from anywhere.
 43
 44We have taken the best part about `express` and `koa` and applied it to fetching
 45API data on the front-end. What this means is that we have a powerful middleware
 46system that we can leverage on the front-end.
 47
 48We built a state management system leveraging the concept of a database schema.
 49We took inspiration from [zod](https://zod.dev) to build an ergonomic and
 50powerful state system leveraging reusable slice helpers. With our schema and
 51custom built store, we can replace all of boilerplate with a single function
 52call `createSchema()`.
 53
 54# Why does `starfx` use [generators](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Generator)?
 55
 56Generators give us -- the library authors -- more control over how side-effects
 57are handled within a javascript runtime environment. There are things that we
 58can do with generators that are just not possible using `async`/`await`. To
 59provide some specific examples, we need the ability to manage async operations
 60as a tree of tasks. We need the ability to have
 61[structured concurrency](https://en.wikipedia.org/wiki/Structured_concurrency)
 62in order to granularly manipulate, manage, spawn, and teardown tasks.
 63
 64Furthermore, `async`/`await` is implemented using generator functions. In
 65`starfx`, not everything we want to `await` is a `Promise`!
 66
 67There is so much more to why generators are awesome but at the end of the day,
 68to the end developer, you can treat generators the same as `async`/`await`.
 69
 70If you are struggling to understand or are getting confused using generator
 71functions, just use the
 72[effection async rosetta stone](https://frontside.com/effection/docs/async-rosetta-stone).
 73
 74We highly recommend reading the
 75[Thinking in Effection](https://frontside.com/effection/docs/thinking-in-effection)
 76page because it should help here.
 77
 78# Data strategy: preload then refresh
 79
 80Preloading is a first-class citizen in `starfx`. It is the primary use case for
 81using it.
 82
 83The idea is simple:
 84
 85> Preload most of your API data in the background and refresh it as the user
 86> interacts with your web app.
 87
 88This is the biggest performance boost to using a single-page app. Since routing
 89happens all client-side, it's beneficial to download data in the background
 90while the user navigates through your web app. While you might be fetching slow
 91API endpoints, it feels instantaneous because the data was preloaded.
 92
 93When the user lands on your web app, initialize a preload thunk that will
 94essentially sync the user's database locally, then when they navigate to a page
 95that requires data, refresh that data as needed.
 96
 97For example, let's say the root page `/` requires a list of users while the
 98`/mailboxes` page requires a list of mailboxes.
 99
100One the root page you would not only fetch the list of users, but you would also
101fetch the lists of mailboxes. When the user finally decides to click on the
102"Mailboxes" page, the page will act as if the data was loaded instantly because
103it was preloaded. So the user sees the data immediately, while at the same time
104you would also re-fetch the mailboxes.