@cplieger/reactive
v2.4.0
Published
Build framework-free TypeScript browser apps from signals, keyed DOM rendering, typed JSON requests and server actions
Maintainers
Readme
reactive
@cplieger/reactive lets you build a TypeScript browser app without a framework, from signals, keyed DOM rendering, typed JSON requests and server actions.
It replaces the change listeners, list re-renders, try/catch blocks and loading flags you would otherwise write between state, the server and the page. It has no runtime dependencies and ships as ESM-only TypeScript source, so it needs a bundler or runtime that compiles TypeScript 6 or later. It ships no widgets, icons or stylesheets; those are in @cplieger/ui. It is licensed under Apache-2.0.
Why use it
@cplieger/reactive is built for apps that draw their interface with plain DOM code.
- A signal write runs every effect that depends on it before it returns, and every subpath shares that one signal graph.
createCollectionandbindListrender a keyed list: a changed item repaints only its row, and a reorder keeps the existing rows.elbuilds elements without HTML strings, andpatchupdates a subtree in place, so focus and scroll position survive a re-render.- Requests never throw, and actions add optimistic updates, rollback and retry for failures you mark as transient.
- No subpath touches the DOM at import, so each one loads under Node, Deno, Bun or Workers.
Consider Solid if you want components, JSX and server-side rendering. Consider TanStack Query if you also need a server-state cache.
Install
npx jsr add @cplieger/reactive
# or
npm i @cplieger/reactiveUsage
A signal holds a value, and an effect re-runs when what it read changes. el builds the elements:
import { effect, el, signal } from "@cplieger/reactive";
const count = signal(0);
const label = el("output");
const button = el("button", { onclick: () => count.value++ }, "Add one");
document.body.append(button, label);
effect(() => {
label.textContent = `Clicked ${count.value} times`;
});Connect your notifications to the actions once at startup, then define each action at module scope and dispatch it from your event handlers:
import { apiAction, configure, retryNetwork } from "@cplieger/reactive/actions";
// Your app's own notifications, such as @cplieger/ui's toasts.
configure({ success: notifySuccess, error: notifyError });
const deleteItem = apiAction<string>({
name: "items.delete",
request: (id) => ({ method: "DELETE", path: `/api/items/${id}` }),
error: "Could not delete the item",
retryable: retryNetwork,
retry: { count: 2, delay: 300 },
});
await deleteItem.dispatch("item-1"); // the result, or null after the error notificationTo call a JSON API directly, create one instance per backend and branch on the result:
import { createFetch } from "@cplieger/reactive/fetch";
const api = createFetch({ baseUrl: "https://api.example.com/v1" });
const res = await api.apiGetRaw<{ name: string }>("/users/me");
if (res.ok) console.log(res.data.name);
else console.error(res.status, res.code, res.error);Subpaths
Import each part from its own subpath. Code that imports these from @cplieger/ui 1.x moves by the table in Moving to reactive 2.4.
| Import from | What it holds |
| --- | --- |
| @cplieger/reactive | everything in /signal and /dom |
| @cplieger/reactive/signal | signals, computed values, effects, owners, resources, stores, collections and the event bus |
| @cplieger/reactive/dom | el, reconcile, bindList, patch and trackHandler |
| @cplieger/reactive/fetch | typed JSON requests |
| @cplieger/reactive/actions | server actions |
| @cplieger/reactive/actions/testing | resetActionFramework for tests |
package.json sets "sideEffects": false, so a bundler drops every subpath you do not import.
API
- Signals, from
/signalor the root:signal,computed,effect,batch,untracked,touch,on,subscribe,isSignal,isComputed,setEffectErrorHandler,createRoot,runWithOwnerandresource. - State, from
/signalor the root:createStore,SignalMap,createCollectionandcreateBus. - DOM, from
/domor the root:el,reconcile,KEY_ATTR,bindList,patchandtrackHandler. - Requests, from
/fetch:createFetchwith itsapiGet,apiPost,apiPut,apiPatchandapiDeletehelpers,withTimeoutandAPI_TIMEOUT_MS. - Actions, from
/actions:configure,configureApi,configureTransport,defineAction,apiAction,transportAction, the errors and retry policyActionError,hasErrorString,classifyFetchError,retryNetworkandRETRY_STANDARD, the idempotency namesIDEMPOTENCY_HEADERandIDEMPOTENCY_COMMAND_FIELD, the helpersdebouncedDispatch,pollAction,pollUntil,bindLoadingState,withAsyncFeedbackandregisterCleanup, and the state readsisPending,pendingCount,subscribeToActions,subscribeByNameandgetActionLog.
The full reference, generated from the doc comments, is on JSR.
A write runs its effects before it returns
When count.value = 1 returns, every effect that depends on count has already run, so the next line reads the DOM those effects wrote. There is no queue and no pending state to wait for.
batch(fn) is the only way to defer. Writes inside it coalesce, and the held effects run once, synchronously, when the outermost batch returns, even when the body throws. To run effects on a later task, make the write on a later task. Signals, stores and collections has the full rules.
Server text is untrusted
- With an absolute
baseUrl, a request path cannot reach another origin. Without one, the path goes tofetch()unchanged, so never build a whole path from untrusted text. - An error message can carry text from the server's response. Your
configureadapter renders it as text, never as HTML. - A failed response's
bodyandcodecome from the server. Check their shape and thestatusbefore you act on them. - Set
sensitive: trueon an action whose arguments or result carry a secret, a token or personal data, so the action log keeps none of them.
Base URLs and untrusted responses and Sensitive actions cover each rule.
Unsupported by design
- The signal and DOM modules leave out ownership outside a root, an
onMountlifecycle, server-side rendering, Suspense, a custom scheduler, a flush barrier such asflushSync, and controlled form inputs. What the signal and DOM modules leave out gives the reasons. - The fetch module leaves out retries, interceptor chains, response caching, global settings and streamed responses. What the fetch module leaves out gives the reasons.
- The actions module leaves out a query cache, framework adapters, a throttle helper and batch dispatch. What the actions module leaves out gives the reasons.
Documentation
- Signals, stores and collections and Building and updating the DOM give the exact rules of
/signaland/dom. - Results and errors, Requests, timeouts and runtimes and Base URLs and untrusted responses cover
/fetch. - Dispatch lifecycle, HTTP and streaming actions and UI and polling helpers cover
/actions. - Moving to reactive 2.4 maps each import from
@cplieger/ui1.x and lists what changed since reactive 2.3.
Credits
- The signal engine follows the design of @preact/signals-core in its dependency graph, its glitch-free computed refresh, its run-on-write effects and its untracked
subscribecallback. - The
on()helper follows Solid'son(), anduntracked()is Solid'suntrack()under the name Preact gives it.createRoot,runWithOwnerand owned nested effects follow Solid's ownership model. onSuccess,onErrorandonSettledfollow TanStack Query's mutation callbacks, andconfigureApifollows RTK Query'sfetchBaseQuery.
Contributing
See CONTRIBUTING.md.
Disclaimer
This project is built with care and follows security best practices, but it is intended for personal / self-hosted use. No guarantees of fitness for production environments. Use at your own risk.
This project was built with AI-assisted tooling using Claude, GPT, and Kiro. The human maintainer defines architecture, supervises implementation, and makes all final decisions.
License
Apache-2.0. See LICENSE.
Third-party attributions are in THIRD_PARTY_NOTICES.md.
