How the Provider runs a Program
When work starts and stops, React Activity, changing props, services, and crashes.
A Provider is where React and a Foldkit Program meet. The Program decides what happens. The Provider decides when it runs, following React's lifecycle. This guide covers that lifecycle: when work starts and stops, how values reach the Program from React, and what happens when it fails.
The examples use the counter from Get started, plus a Command that increments it after one second. Foldkit's Commands guide explains Commands themselves.
const WaitToIncrement = Command.define("WaitToIncrement", {
messages: [Message.CompletedWaitToIncrement],
execute: Effect.sleep("1 second").pipe(Effect.as(Message.CompletedWaitToIncrement())),
})Rendering runs nothing
During render, including server rendering, the Provider only computes the first Model from init. No Command, Subscription, or Managed Resource starts.
React may render a Provider more than once, or throw a render away. Keep init and update pure, so a repeated or abandoned render has no effect.
The Provider runs work while it is mounted
- When React mounts the Provider in the browser, the Provider starts the Program's Managed Resources, then its init Commands and Subscriptions.
- When React unmounts the Provider, it stops all of that work. A Command still waiting, such as
WaitToIncrement, never sends its Message. - Each mounted Provider has its own Model. Two Providers of the same application don't share state.
Choose what happens when React Activity hides the Provider
<Activity mode="hidden"> hides a Provider without unmounting it. The Provider stops its work but keeps its Model. When Activity shows it again, the Provider starts from that Model.
Init Commands that were stopped start again, and init Commands that had finished don't run twice. For Commands that update returned, choose one of these options in Application.define:
| Option | What happens to a stopped Command | Use it for |
|---|---|---|
restartInterrupted |
It starts again | Work that is safe to repeat, such as a fetch |
onReactivate |
The Provider passes it to you, and you return a Message for update |
Work you shouldn't repeat, such as a write |
retainInactive |
Nothing stops while the Provider stays hidden for less than this time | Quick hides, such as switching tabs |
const Counter = Application.define(counter, {
restartInterrupted: (command) => command.name === "WaitToIncrement",
})Without any option, a stopped WaitToIncrement is dropped, and update never receives CompletedWaitToIncrement.
Send changing values with useInbound
The Provider reads init once, when it mounts. When a value from React keeps changing, such as a prop or a route parameter, send each change to update as a Message:
function SyncStep({ step }: { readonly step: number }) {
Counter.useInbound(step, (step) => Message.ChangedStep({ step }))
return null
}Render SyncStep inside the Provider, and put the first value in init. useInbound skips the first value and sends a Message only when the value changes.
Don't remount the Provider to pass a new value. Remounting throws away the Model and stops its Commands. Use a router applies this to URLs.
Give Commands their services
When Commands need a service, such as an API client, pass a Layer as resources:
const Cart = Application.define(cart, { resources: CartApi.layer })The Layer must be complete: it can't require other services or fail. Services that the Program's Managed Resources supply need no Layer.
Effect code that runs a Program without React can use Store.make from react-foldkit/store instead. It takes services from the surrounding Effect.
Show something when the Program fails
When update or a Command fails, the Provider stops the Program and renders crash.view in place of its children. The view receives the failure, the Model at that moment, the Message that caused it, and restart, which mounts the Provider again from init.
const Counter = Application.define(counter, {
crash: {
view: ({ cause, restart }) => (
<div role="alert">
<pre>{Cause.pretty(cause)}</pre>
<button onClick={restart}>Start again</button>
</div>
),
report: ({ cause, message }) => Effect.logError("Counter crashed", message, cause),
},
})report runs in the background, for example to send the failure to a logging service. A Provider's own crash prop replaces either callback for that Provider. These options mirror Foldkit's crash view.