Move to Foldkit
Move a React app to Foldkit one feature at a time, without a rewrite.
React Foldkit exists so that a React app can become a Foldkit app without a rewrite. You move one feature at a time, and the app keeps working and shipping after every step. This guide shows the whole path.
Why one feature at a time
A rewrite stops feature work until it is done, then ships everything at once. Moving one feature at a time keeps each step small enough to review, test, and release on its own. The parts you haven't touched keep running as they are.
The path has two stages
| Stage | What changes | Who renders the feature |
|---|---|---|
| 1. Move the logic | The feature's state and side effects move into a Foldkit Program | React, through React Foldkit |
| 2. Move the view | The feature's React components are rewritten as a Foldkit view | Foldkit's runtime |
Stage 1 is where React Foldkit does its work, and it is most of the job. A feature that finished stage 1 already has a pure update, Commands for its side effects, Scene tests, and Foldkit's DevTools. You can stay in stage 1 for as long as you need.
Stage 1: move the logic into a Program
Do this for one feature, such as a cart:
- Write the feature's Program with
Program.makefromreact-foldkit/program. The Program is plain Foldkit, so Foldkit's architecture guide explains its parts. - Define the application with
Application.define(cart), and render its Provider where the feature mounts. - In the feature's components, replace
useStateanduseEffectwithuseModelto read the Model anduseSendto send Messages. - Test the feature with Scene from
react-foldkit/scene, as Test views with Scene shows.
After step 3, a component only reads the Model and sends Messages:
function CartButton() {
const count = Cart.useModel((model) => model.items.length)
const send = Cart.useSend()
return <button onClick={() => send.ClickedAdd({ item: "Socks" })}>Cart ({count})</button>
}Then move the next feature. Features that are still plain React keep working next to the ones you moved.
Keep stage 2 cheap
Stage 2 rewrites only the view. Everything else in the feature moves unchanged, as long as you follow these rules during stage 1:
- Put the Program in a module that imports nothing from React.
- Keep side effects in Commands. A fetch in a
useEffector an event handler has to be rewritten later, while a Command moves as it is. - Keep the feature's state in the Model. A
useStatein a component is state that a Foldkit view can't see. - Keep navigation in Commands, as Use a router shows.
The presets in react-foldkit/eslint report some of these mistakes, such as navigation outside a Command and, with strictConfig, useState in a view.
Stage 2: move the view to Foldkit
A Foldkit view is not a React component, so React can't render it. Foldkit's own runtime renders it into a DOM element. Moving a feature's view therefore means that Foldkit's runtime takes over that part of the page, and runs the same Program in place of the React Foldkit Provider.
First, write the view. It reads the same Model and sends the same Messages as the React component:
import type { Html, HtmlBuilder } from "foldkit/html"
import { Message, type Model } from "./program"
export const view = (model: Model, h: HtmlBuilder<Message>): Html =>
h.button([h.OnClick(Message.ClickedAdd({ item: "Socks" }))], [`Cart (${model.items.length})`])Foldkit's view guide covers attributes, lists, and keyed elements. Then pick one of the two ways below to hand the feature to Foldkit's runtime.
Hand over one feature while the page stays in React
Foldkit's Runtime.embed runs a Foldkit app inside a page that another framework owns. A small React component keeps an empty element, and Foldkit renders the feature inside it:
import { Runtime } from "foldkit"
import { useEffect, useRef } from "react"
import { cart } from "./program"
import { view } from "./view"
export function Cart() {
const container = useRef<HTMLDivElement>(null)
useEffect(() => {
const handle = Runtime.embed(Runtime.makeElement({ ...cart, view, container: container.current }))
return handle.dispose
}, [])
return <div ref={container} />
}Runtime.makeElement takes the Program as it is, because its field names match. When the Program needs services, pass the same Layer you gave Application.define as resources. handle.dispose stops the feature when React unmounts the component.
After this step, the feature's Model lives in Foldkit's runtime, not in a React Foldkit Provider. React components outside the feature can't read it with useModel anymore. They exchange values with it through Ports, which Foldkit's embedding guide explains. So start with features that share little state with the rest of the page.
Hand over the whole app at the end
When every feature's logic lives in a Program, you can switch the whole page at once:
- Combine the features' Programs into one application Program. Child Programs become Foldkit Submodels.
- Rewrite the remaining views as Foldkit views.
- Replace React's root with
Runtime.makeApplication, and the React router with Foldkit's routing. - Remove
react-foldkitfrom your dependencies.
What moves unchanged
| Part of the feature | In stage 2 |
|---|---|
Model, Messages, update, init, and Commands |
Unchanged. They import from effect and foldkit only |
| Subscriptions and Managed Resources | Unchanged |
The Program from Program.make |
Passes to Foldkit's runtime as it is |
Services in resources |
The same Layer goes to the runtime's resources field |
| Scene tests | One import changes, from react-foldkit/scene to foldkit/scene |
| Story tests | Unchanged, because they call update directly |
| React components | Rewritten as a Foldkit view |
restartInterrupted, onReactivate, and retainInactive |
Removed. They exist only because React can hide a Provider |
The Scene test change looks like this:
- import { Command, click, expect, given, role, scene } from "react-foldkit/scene"
+ import { Command, click, expect, given, role, scene } from "foldkit/scene"