Skip to content
Verified

@xuda/core

The dependency-free reactive engine the platform, the compiler and the demo apps all mount on.

@xuda/core is the Xuda reactive engine (signals, scheduler, keyed list diff, reactive renderer, router) as a dependency-free ESM package. It reads and writes no globals on import: no func, no SESSION_OBJ, no window, no document.

The one public package in this part of the docs

@xuda/core's package.json carries "private": false. It is the only package among the three covered in this section (alongside @xuda/compiler and @xuda/vite-plugin-xu, both private: true) built to be depended on outside this repository.

It is also not a separate engine from the one the platform already ships: the package's own build:globals script (esbuild src/globals.js --bundle ... --outfile ../../runtime/js/xuda_core.globals.js) is how runtime/js/xuda_core.globals.js, the platform's own shipped reactive-renderer bundle, gets built.

The reactive surface

js
import { ref, reactive, computed, effect, watch, effectScope } from '@xuda/core';

There is one dependency graph, one owner tree, one batch buffer and one scheduler underneath all of it: a ref read inside an effect() tracks and re-runs it, the same as a signal read inside a watch(). computed here accepts a getter, or a { get, set } pair for a writable computed.

js
const state = reactive({ count: 0 });
state.count++;             // no .get(), no .set()

const n = ref(0);
n.value++;

effectScope() answers "who disposes this": a named owner you can hand around, nest and stop in one call, instead of hand-rolling a bag of disposers.

js
const scope = effectScope();
scope.run(() => {
  effect(() => { /* ... */ });
  watch(source, callback);
  onScopeDispose(() => io.disconnect());
});
scope.stop();

A component instantiated through createApp() already owns one of these: its <script> runs inside the component's own detached scope, so an effect written there is disposed automatically when the component unmounts.

The low-level primitive

signal(initial) (.get(), .set(), .peek(), .notify(), .subscribe()) and signalComputed are the engine's own cells underneath ref and computed. They are exported and fully supported, not removed, because the renderer and the legacy bridge are built on them, and because signal.notify(), re-running subscribers with no value change, has no ref equivalent. Application code should reach for ref and computed instead; these two names are documented as the layer below, not deprecated at runtime (a warning on signal() would fire per row scope and per panel param, thousands of times a screen, for code doing exactly the right thing at that layer).

The app entry point

js
import { createApp } from '@xuda/core';
import App from './App.xu';

createApp(App).mount('#app');

App is a compiled .xu module, produced by @xuda/compiler or the vite-plugin-xu build step. createApp builds the seven injected deps the renderer needs over the thunk table the module's setup() returns, creates the renderer, and mounts the component tree. It is not a second renderer: the compiled path and the interpreted platform path share render.js.

examples/hello is the concrete, tested version of this: createApp(App).mount('#app') over a compiled App.xu with a counter, a conditional and a keyed list.

The renderer, dependency-injected

js
import { create_renderer } from '@xuda/core';
import { reactive } from '@xuda/core/reactivity';

create_renderer(deps) is DOM-agnostic. Everything environmental arrives through one deps object, and the smallest honest host needs exactly seven of them: document (createElement / createTextNode / createComment), evaluate (a tracked, synchronous expression evaluator), cast_bool (truthiness for xu-render / xu-if), resolve_rows (a tracked row-array resolver for xu-for), row_key (stable row identity), write_field (xu-bind writes) and dispatch_event (xu-on:* handlers). packages/core/demo builds exactly this over a plain reactive({...}) object, with no SESSION_OBJ, no datasource layer and no legacy bridge anywhere underneath.

Two silent DOM-contract traps, if you write your own adapter

A deps.document node with no nodeType is read as a jQuery object rather than a real DOM node, which can nest every row inside its predecessor with no thrown error. A node with no remove() turns a dropped row into a silently rejected promise: the list stops updating and nothing is logged. create_adapter in the demo guards both by throwing at node-creation time; pass { guard: false } to opt out once you understand why the guard exists.

Diagnostics and whenElement

onDiagnostic, getDiagnostics, diagnosticCount and resetDiagnostics turn the engine's silent give-ups into one observable channel, rather than scattered console.error calls, so a host adapter or a test can subscribe to them by code. whenElement runs a callback once a node exists: it asks once, then re-asks on the scheduler's commit phase (exactly when the DOM settles, before paint), and a wait still unsatisfied after twenty settled renders reports itself by name rather than giving up silently.

The router

createRouter, createWebHistory, createWebHashHistory, createMemoryHistory, useRouter and useRoute ship from the same package. The current route is @xuda/core's own reactive, and history comes from the platform, so using it adds no dependency of its own.

Package exports

Node 18 or newer is the declared engine floor.