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 loading strategy: `stale-while-revalidate`
 79
 80The idea comes from HTTP caching mechanisms:
 81[`stale-while-revalidate`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control#stale-while-revalidate)
 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 strategy removes the need to show loaders throughout your app.
 89
 90Preloading is a first-class citizen in `starfx`. It is the primary use case for
 91using it.
 92
 93This is the biggest performance boost to using a single-page app. Since routing
 94happens all client-side, it's beneficial to first download data in the
 95background while the user navigates through your web app. While you might be
 96fetching slow API endpoints, it feels instantaneous because the data was already
 97loaded before a pager needed to display it.
 98
 99When the user lands on your web app, initialize a preload thunk that will sync
100the user's database locally, then when they navigate to a page that requires
101data, refresh that data as needed.
102
103For example, let's say the root page `/` requires a list of users while the
104`/mailboxes` page requires a list of mailboxes.
105
106On the root page you would fetch the list of users as well as the lists of
107mailboxes. When the user finally decides to click on the "Mailboxes" page, the
108page will act as if the data was loaded instantly because it was preloaded. So
109the user sees the data immediately, while at the same time you would also
110re-fetch the mailboxes.