sudomaker/refui

rEFui

Overview

Apply rEFui’s retained-mode + signals model correctly, choose the right JSX mode/renderer, and fix reactivity/lifecycle issues without importing patterns from other UI frameworks.

Read This First

Before making any change, skim references/reactivity-pitfalls.md. It prevents most retained-mode mistakes.

Core Pitfalls (skim)

• JSX is evaluated once; {signal.value} in JSX is static. Use {signal} or a derived $(() => ...).
• In-place array/object mutation requires sig.trigger() (or replace with a new value).
• Effects re-run when any read signal changes; avoid writing to those signals without guards.
• Context values are stable; provide signals in context if consumers must react.
• Passing a signal/computed directly to rEFui control-flow is correct: <If condition={sig}> and <If condition={computed}> are intended usage. The pitfall is conditional .value reads inside JS/derived code that skip later dependencies.

General guide

Mental model (retained mode)

• Component bodies are setup: they run once; they do not “re-render”.
• JSX is evaluated once; signals update the already-built UI incrementally.
• If something “doesn’t update”, you almost always read .value too early (non-reactively) or mutated in place without trigger().

Signals & reactivity

• State: const count = signal(0)
• Reactive JSX: {count} (not {count.value})
• Derived: const label = $(() => Count: ${count.value}) and then {label}
• In-place mutation: call sig.trigger() after mutating arrays/objects.

import { signal, $ } from 'refui'

const Counter = () => {
	const count = signal(0)
	return (
		<button on:click={() => count.set(count.value + 1)}>
			{$(() => `Count: ${count.value}`)}
		</button>
	)
}

Effects & cleanup

• Reactive effect: watch(() => { ...reads signals... })
• Setup/cleanup: useEffect(() => { ...; return () => cleanup })
• Teardown-only: onDispose(() => cleanup)
• Scheduling: if you need “after updates applied”, await nextTick().

Control flow components

• Conditional UI: <If condition={cond}>{() => <Then />}{() => <Else />}</If>
• Lists: <For entries={items} track="id">{({ item, index }) => ...}</For>
• Inline dynamic subtree with lifecycle: <Fn ctx={something}>{(ctx) => ...}</Fn>
• For has no fallback; for empty states, wrap with <If>.
• If the condition already exists as a signal/computed, pass it directly. Do not “fix” <If condition={someSignal}> into extra .value plumbing.

import { signal, $, If, For } from 'refui'

const App = () => {
	const items = signal([{ id: 1, name: 'A' }])
	return (
		<If condition={$(() => items.value.length)}>
			{() => <For entries={items} track="id">{({ item }) => <div>{item.name}</div>}</For>}
			{() => <div>Empty</div>}
		</If>
	)
}

Async UI

• <Async> for a single promise boundary.
• <Suspense> to group multiple async subtrees under one fallback.
• lazy(() => import(...)) for code-splitting; pair with fallback boundaries. See references/async-suspense-transition.md for the “rules of engagement”.

Context

Use context for shared subtree values. If consumers must react to changes, provide a signal as the context value.

import { signal, $, createContext, useContext } from 'refui'

const Theme = createContext(signal('light'), 'Theme')

const Button = () => {
	const theme = useContext(Theme)
	return <button class:dark={$(() => theme.value === 'dark')}>OK</button>
}

Non-Reflow/custom renderer: wrap Provider children in a function so they inherit context: <Theme value={x}>{() => <Button />}</Theme>.

Mounting (DOM / HTML)

• DOM renderer (browser): createDOMRenderer(defaults).render(target, App)
• HTML renderer (SSR/SSG): createHTMLRenderer().serialize(createElement(App, props))
• JSX + renderer selection: see references/jsx-and-renderers.md (automatic vs classic transform).

import { createDOMRenderer } from 'refui/dom'
import { defaults } from 'refui/browser'

createDOMRenderer(defaults).render(document.getElementById('app'), App)

DOM directives (browser preset)

• Events: on:click={fn} (+ on-once:*, on-passive:*, on-capture:*)
• Classes/styles: class:active={boolOrSignal}, style:color={valueOrSignal}
• Attributes vs props: attr:* (SVG/read-only), prop:* (force property write)
• Macros: m:* for reusable DOM behaviors (renderer-registered handlers)

Default Policy: Use rEFui Built-ins First

When implementing a requirement, prefer rEFui’s built-in primitives (signals/components/extras/renderers) over custom plumbing. Only fall back to a custom implementation when:

• rEFui has no built-in primitive that matches the requirement, and
• the project’s rEFui version lacks an equivalent helper, and
• you can’t express it cleanly as a DOM macro (m:*) or small reusable component.

Before writing code, consult references/dos-and-donts.md to avoid React-style mistakes.

Quick Triage (do this first)

1. Identify JSX mode in the target repo:
   • Automatic runtime: look for jsx: 'automatic' + jsxImportSource: 'refui' (Vite/esbuild) or jsxImportSource: "refui" (tsconfig/Bun).
   • Classic transform: look for jsxFactory: 'R.c' + jsxFragment: 'R.f' (Vite/esbuild) or /** @jsx R.c */ file pragmas.
2. Identify the host renderer:
   • Browser apps: createDOMRenderer(defaults) from refui/dom + refui/browser (or refui/presets/browser in older repos).
   • SSR/SSG: createHTMLRenderer() from refui/html, then serialize().
   • Reflow logic-only modules: refui/reflow (often injected via jsxInject: import { R } from 'refui/reflow' in classic mode).
3. Confirm rEFui version (it changes API details across repos). Prefer the repo’s local docs or installed refui exports.

If you want an automated scan for JSX mode + common pitfalls, run node scripts/refui-audit.mjs <path> from inside this skill folder.

When Usage Is Unclear (consult MCP docs)

If you are unsure about a rEFui API, behavior, or best practice and cannot inspect the library source or the docs:

• Use Context7 MCP to pull authoritative, up-to-date library docs/snippets:
  • First resolve the library: mcp__context7__resolve-library-id with libraryName: "refui".
  • Then query: mcp__context7__query-docs for the specific API/task (e.g. “For track vs indexed”, “createDOMRenderer macros”, “nextTick vs tick semantics”, “classic vs automatic JSX setup”).
• Use DeepWiki MCP for repository-level questions (when the upstream repo is available):
  • mcp__deepwiki__read_wiki_structure then mcp__deepwiki__ask_question on SudoMaker/rEFui for conceptual/system questions or “where is X documented?”.

If MCP docs still leave ambiguity, ask the user for: the refui version, their bundler config (Vite/esbuild/Bun/TS/Babel), and a minimal repro snippet.

“Which rEFui feature should I use?” (fast mapping)

Use these references when choosing a built-in solution:

• Idiot-proof do/don’t checklist: references/dos-and-donts.md
• Async UI: references/async-suspense-transition.md
• Overlays/teleports/rich HTML/custom elements: references/portals-parse-custom-elements.md
• Lists/identity/caching/perf: references/lists-cache-memo.md
• Project setup: references/project-setup.md

Non-Negotiables (retained mode)

• Do not write React/Vue/Solid/Svelte primitives (useState, hooks, VDOM assumptions, $: blocks, etc.). Map them to rEFui signals/effects.
• Treat component bodies as setup (constructor-ish). JSX is evaluated once; signals drive incremental updates afterward.
• Keep reactive reads reactive:
  • ✅ Use a signal directly: <div>{count}</div>
  • ✅ Wrap derived expressions: <div>{$(() => Count: ${count.value})}</div> or <div>{computed(() => ...)}</div>
  • ❌ Avoid inline .value in JSX: <div>{count.value}</div> (evaluates once, won’t update)
• Control-flow note:
  • ✅ <If condition={flag}> when flag is already a signal/computed
  • ✅ <If condition={$(() => count.value > 0)}> for a derived condition
  • ❌ Treating <If condition={flag}> as a reactivity smell by itself
• Remember scheduling: signal effects/computed flush at the end of the tick; use await nextTick() when you must observe derived updates.

Default Patterns (copy these mentally)

• State: const x = signal(initial)
• Derived: const y = $(() => /* uses x.value */) (or computed(() => ...))
• Effects: watch(fn) for reactive computations; useEffect(setup) for setup+cleanup; onDispose(cleanup) for teardown.
• Lists:
  • Keyed: <For entries={items} track="id">{({ item }) => ...}</For>
  • Unkeyed (perf experiments / reorder heavy): UnKeyed from refui/extras/unkeyed.js
  • If mutating arrays/objects in place: call sig.trigger() after mutation.
• Async:
  • <Async future={promise} fallback={...} catch={...}>{({ result }) => ...}</Async>
  • <Suspense> for grouping async subtrees
  • async components are supported; pair with fallbacks when needed.
• DOM directives/events (DOM renderer):
  • Events: on:click={...}, plus options on-once:*, on-passive:*, on-capture:*
  • Attributes vs props: prefer attr: for SVG or when a DOM prop is read-only; use prop: to force a property set.
  • Preset directives (browser preset): class:x={boolSignal}, style:color={valueOrSignal}
  • Macros: m:name={value} where name is registered on the renderer.
• Refs/handles:
  • $ref={sig} to receive a node/instance in sig.value
  • $ref={(node) => ...} callback form
  • Prefer expose prop for imperative child handles (v0.8.0+).

Workflows

Add a feature safely

1. Keep renderer creation at the entry point; do not create renderers inside components.
2. Localize state: prefer per-component signals over global blobs; use extract/derivedExtract to reduce fan-out.
3. For repeated DOM behaviors, register a macro and use it via m:* rather than duplicating manual DOM code.
4. For lists, choose keyed <For> unless you have a measured reason to use unkeyed.

Set up a new project (when asked)

1. Ask only: preferred package manager (npm/pnpm/yarn/bun) and language (JS/TS). Do not ask runtime.
2. Default to JSX automatic runtime + JavaScript + refui latest from npm unless the user specifies otherwise.
3. Follow references/project-setup.md.

Repo Navigation (load only if needed)

Read these files when you need deeper details:

• references/project-triage.md for determining JSX mode/renderer/version from a project that uses rEFui as a dependency.
• references/project-setup.md for scaffolding a new project (default: JSX automatic runtime + pure JS).
• references/jsx-and-renderers.md for choosing classic vs automatic and DOM/HTML/Reflow specifics.
• references/reactivity-pitfalls.md for high-signal debugging checklists and anti-patterns.
• references/dos-and-donts.md for per-API/component do’s and don’ts that prevent React-mindset mistakes.
• references/async-suspense-transition.md for <Async>, <Suspense>, lazy, and Transition.
• references/portals-parse-custom-elements.md for portals/teleports, HTML parsing, and custom elements.
• references/lists-cache-memo.md for <For>, identity, UnKeyed, caching, and memoization.

Resources

scripts/

• scripts/refui-audit.mjs: quick scan for JSX mode + common .value-in-JSX pitfalls.

references/

• references/project-triage.md
• references/jsx-and-renderers.md
• references/reactivity-pitfalls.md
• references/dos-and-donts.md
• references/async-suspense-transition.md
• references/portals-parse-custom-elements.md
• references/lists-cache-memo.md
• references/project-setup.md

docs/

All documents live in this directory. Check detailed usages of a certain API before you implement anything with them.