Quickstart
A counter: one entity, one action that takes a second, and a button that shows the action is running. Each step shows React first, then Solid.
Create the app
npm create treflex@latest counter -- --template react
cd counter
npm install
npm run devnpm create treflex@latest counter -- --template solid
cd counter
npm install
npm run devThe app is an App root entity holding the counter below as a feature in its own folder, with a selector, tests, Biome and ESLint with treflex's lint rules, hot reload, and a count that survives a reload. Its increment is marked leading, so a second increment dispatched while one runs is dropped rather than queued, which its test shows. The template requires a durable name on every action, so increment is marked named(increment, "Counter/Increment") too. Its README.md says what's where.
Add treflex to an existing app
Start from a Vite app, or make one:
npm create vite@latest counter -- --template react-ts --no-interactive
cd counter
npm install treflex treflex-reactnpm create vite@latest counter -- --template solid-ts --no-interactive
cd counter
npm install treflex treflex-solid solid-jsRequirements has what an app's build and tests need.
Write the counter
Replace the entry file, src/main.tsx in React and src/index.tsx in Solid, with:
import { createRoot } from "react-dom/client";
import { createRuntime, defineEffect, type IActionGenerator, type IEffect, type IEntity, implementation } from "treflex";
import { createEntityFeature, TreflexProvider, useInFlight, useRoot } from "treflex-react";
interface ICounter extends IEntity {
Count: number;
}
interface IDelay extends IEffect {
Type: "Counter/Delay";
Ms: number;
}
const delay = defineEffect<IDelay, void>("Counter/Delay");
const delayImpl = implementation(delay, (effect) => new Promise<void>((resolve) => setTimeout(resolve, effect.Ms)));
function* increment(draft: ICounter): IActionGenerator {
yield* delay({ Ms: 1000 });
draft.Count++;
}
const Counter = createEntityFeature<ICounter>("Counter")({ increment });
const CounterView = Counter.provider(() => {
const counter = Counter.use();
const counting = useInFlight(increment, counter.state);
return (
<button disabled={counting} onClick={() => counter.increment()}>
{counting ? "Counting..." : `Count: ${counter.state.Count}`}
</button>
);
});
const runtime = createRuntime<ICounter>({ $Id: "Counter", Count: 0 });
runtime.registerImplementation(delayImpl);
function Root() {
return <CounterView state={useRoot<ICounter>()} />;
}
createRoot(document.getElementById("root")!).render(
<TreflexProvider value={runtime}>
<Root />
</TreflexProvider>
);import { render } from "solid-js/web";
import { createRuntime, defineEffect, type IActionGenerator, type IEffect, type IEntity, implementation } from "treflex";
import { createEntityFeature, TreflexProvider, useInFlight } from "treflex-solid";
interface ICounter extends IEntity {
Count: number;
}
interface IDelay extends IEffect {
Type: "Counter/Delay";
Ms: number;
}
const delay = defineEffect<IDelay, void>("Counter/Delay");
const delayImpl = implementation(delay, (effect) => new Promise<void>((resolve) => setTimeout(resolve, effect.Ms)));
function* increment(draft: ICounter): IActionGenerator {
yield* delay({ Ms: 1000 });
draft.Count++;
}
const Counter = createEntityFeature<ICounter>("Counter")({ increment });
const CounterView = Counter.provider(() => {
const counter = Counter.use();
const counting = useInFlight(increment, () => counter.state);
return (
<button disabled={counting()} onClick={() => counter.increment()}>
{counting() ? "Counting..." : `Count: ${counter.state.Count}`}
</button>
);
});
const runtime = createRuntime<ICounter>({ $Id: "Counter", Count: 0 });
runtime.registerImplementation(delayImpl);
render(
() => (
<TreflexProvider value={runtime}>
<CounterView state={runtime.state} />
</TreflexProvider>
),
document.getElementById("root")!
);Run npm run dev and click the button. It reads "Counting..." and stays disabled, then shows the new count.
One file keeps the parts together to read, and an edit to it starts the count over. An app from npm create treflex splits them, so an edit to an action, a selector or a view applies in place with the state kept.
What each part is
ICounteris an entity: an object in the state tree with an$Id. 1. An entity and its state.delayis an effect, a request to the outside world as plain data, anddelayImplis what answers it. 2. An action, and holds.incrementis an action: a generator that writes to its entity throughdraftand calls effects withyield*. It holds the counter until it finishes, so a secondincrementqueues behind it.Counteris a feature:Counter.providermounts a view on the counter, andCounter.use()gives that view the counter's state and one method per action. 3. Views.useInFlightis true whileincrementruns or waits its turn on the counter. Nothing in the counter records it.
The guide builds a whole app this way, a step per page.