Related Pages

Related topics: Runtime Engine: Fiber Model, Reconciliation, and State Machine, Reactive System: Signals, Effects, and Dependency Tracking, JSX Runtime, Components, and Control Flow Primitives

Introduction and Getting Started

CReact is an open-source project that provides a React-compatible component model and rendering pipeline, packaged as a workspace of libraries, documentation, and example applications. This page introduces the repository's purpose, explains how the project is organized, and walks through the minimum steps required to install the core package and render a first component.

What CReact Is

CReact (short for "Component React") is positioned by its maintainers as a component-based UI library that exposes APIs familiar to developers who already know React. The top-level landing page describes the project as the entry point users reach from the documentation site, and the surrounding workspaces (packages, apps, libs) show the same library being consumed in three different contexts: as a published package, as the engine that powers the documentation site, and as the runtime for example apps.

Source: README.md:1-40 Source: apps/website/src/pages/landing/index.tsx:1-60 Source: packages/creact/README.md:1-40

Repository Layout

The monorepo is split into three top-level workspaces that mirror the audiences the project serves:

This three-part structure means the same creact package that is documented under apps/website/src/pages/docs/getting-started/installation/ is also the package executed by libs/examples/apps/getting-started-tour/first-entry.tsx, which keeps documentation and examples in lock-step with the library source.

Source: apps/website/src/pages/docs/getting-started/installation/index.tsx:1-40 Source: libs/examples/apps/getting-started-tour/first-entry.tsx:1-40

Installing the Core Package

The installation route under docs/getting-started/installation is the canonical onboarding entry for new users. The English i18n resource at apps/website/src/i18n/resources/en/docs/getting_started/installation.json supplies the localized copy that the page renders, including the steps, the package name, and the manager command shown to the reader. Because the strings live in a JSON resource rather than being hard-coded into the route component, the same installation instructions can be translated without touching the React tree.

In practice, installation follows the standard Node.js package-manager pattern: the user picks a package manager, the documentation shows the corresponding add / install command referencing the creact package, and the user then imports the runtime APIs from the same package in their own entry file. The first-entry.tsx example in libs/examples/apps/getting-started-tour is the concrete reference for what that entry file looks like after installation.

Source: apps/website/src/pages/docs/getting-started/installation/index.tsx:40-120 Source: apps/website/src/i18n/resources/en/docs/getting_started/installation.json:1-60 Source: packages/creact/README.md:20-80

A Minimal First Entry

The smallest meaningful CReact program is the "first entry" sample in libs/examples/apps/getting-started-tour/first-entry.tsx. It demonstrates the three pieces every CReact application needs:

1. Import the entry/render API and the component-creation API from the installed creact package.
2. Define a component that returns a tree of elements describing the UI to render.
3. Call the render entry point with that component and a target DOM container.

The same shape applies whether the target is the documentation site, an example app, or a user project. Once the first component renders successfully, subsequent learning material — hooks, state, event handling, and the broader API surface — is built on top of this starting point rather than introduced as a parallel concept.

Source: libs/examples/apps/getting-started-tour/first-entry.tsx:1-80

Suggested Workflow After Installation

The recommended progression for a new user, derived from how the repository itself is wired, looks like this:

flowchart LR
  A[Read README] --> B[Install creact package]
  B --> C[Write first-entry.tsx]
  C --> D[Render component]
  D --> E[Explore libs/examples]
  E --> F[Build app in apps/website or own project]

Each arrow corresponds to a file in this page: the top-level README.md is the starting point, the installation route on the documentation site teaches npm/pnpm setup, the getting-started-tour app shows the first component, and the broader libs/examples directory plus the apps/website source become the next references once the basics work.

Source: README.md:1-80 Source: apps/website/src/pages/landing/index.tsx:1-80 Source: apps/website/src/pages/docs/getting-started/installation/index.tsx:1-80 Source: apps/website/src/i18n/resources/en/docs/getting_started/installation.json:1-40 Source: libs/examples/apps/getting-started-tour/first-entry.tsx:1-60

Where to Go Next

After completing the steps above, the natural next stops inside the repository are:

• The packages/creact directory, to read the library's own README and exported API surface.
• Additional entries under libs/examples/apps/, to see slightly larger programs that exercise more of the API.
• The remaining docs/getting-started/* routes on the website, which continue the onboarding flow beyond installation into concepts, configuration, and common patterns.

Together these three workspaces — package, examples, and website — form the complete "Introduction and Getting Started" experience for CReact.

Related Pages

Related topics: Reactive System: Signals, Effects, and Dependency Tracking, JSX Runtime, Components, and Control Flow Primitives, Stores, Context, and Owner-Based Memory

Runtime Engine: Fiber Model, Reconciliation, and State Machine

The creact runtime engine is the core subsystem that turns a tree of component invocations into an interactive UI instance. It owns three tightly coupled responsibilities: building and mutating a Fiber tree that represents the current render, running a reconciliation algorithm that diffs new renders against that tree, and driving a finite state machine that governs a fiber's lifecycle from creation through effect commit and unmount.

High-Level Architecture

The runtime is split into small cooperating modules under packages/creact/src/runtime:

Together they implement a cooperative, single-pass reconciler that mirrors React's mental model but is small enough to read end-to-end. Source: packages/creact/src/runtime/fiber.ts:1-80, packages/creact/src/runtime/render.ts:1-60.

Fiber Model

A fiber is the unit of work. It is a plain object with three pointer fields (child, sibling, return) that link it into a tree without nested arrays, allowing the renderer to walk it iteratively. Source: packages/creact/src/runtime/fiber.ts:12-78.

Key fields on a fiber include:

• type — the component function or host element name the fiber represents.
• props / children — the props passed to that component.
• instance — the associated Instance object holding hooks and refs.
• flags — a bitmask of pending work (Placement, Update, Deletion, Effect).
• status — current state-machine status.
• alternate — the previous fiber from the prior render, used as the diff source.

Sibling fibers are stored as a singly linked list via sibling, so reconcileChildren can iterate them with while (current !== null). Source: packages/creact/src/runtime/reconcile.ts:40-95, packages/creact/src/runtime/fiber.ts:60-78.

Reconciliation

Reconciliation is triggered whenever a component re-renders. The scheduler enqueues a microtask, which calls run.ts's work loop. The loop calls reconcileFiber(parent, previous, next) for each work unit. Source: packages/creact/src/runtime/reconcile.ts:1-40, packages/creact/src/runtime/run.ts:20-70.

The algorithm follows three rules:

1. Same type, same key — reuse the previous fiber, copy its instance, and update props. Mark with Update flag if props changed.
2. Different type — mark the old fiber with Deletion, create a new fiber with Placement, and let commit tear it down.
3. Children — call reconcileChildren(parent, oldChildren, newChildren) which pairs old and new fibers by position (and key when present), producing a new sibling chain.

The result of reconciliation is a fiber tree where each node carries flags describing the work to perform; no DOM or effect runs yet. Source: packages/creact/src/runtime/reconcile.ts:60-140.

State Machine

Each fiber is driven through a small finite state machine defined in state-machine.ts:

• Pending — newly created, not yet committed.
• Mounted — committed to the host and visible.
• Dirty — re-render scheduled but not yet processed.
• Unmounted — removed from the host, eligible for cleanup.

Transitions are invoked from the work loop and from commit hooks. For example, a freshly created fiber is Pending, becomes Mounted after commitMount, transitions to Dirty when markDirty(fiber) is called from a state setter, and reaches Unmounted when the parent places a Deletion flag on it. Source: packages/creact/src/runtime/state-machine.ts:1-90, packages/creact/src/runtime/run.ts:80-130.

stateDiagram-v2
    [*] --> Pending: createFiber
    Pending --> Mounted: commitMount
    Mounted --> Dirty: markDirty (setState)
    Dirty --> Pending: beginWork
    Mounted --> Unmounted: Deletion flag
    Dirty --> Unmounted: Deletion flag
    Unmounted --> [*]

The instance module cooperates with the state machine: instance.ts exposes enqueueEffect(fiber, effect) and runEffects(fiber) which only fire effects when the fiber is Mounted, preventing leaks from already-unmounted trees. Source: packages/creact/src/runtime/instance.ts:30-110.

Work Loop and Commit

run.ts is the orchestrator. Its main loop performs begin-work (reconciliation) and complete-work (commit) in two passes:

• Begin phase — walks root.child recursively, calling reconcileFiber to compute flags.
• Complete phase — walks back up via return, applying Placement, Update, and Deletion flags to the host and firing effects in commit order.

The scheduler ensures beginWork is called at most once per microtask batch, coalescing multiple setState calls from a single event into one render. Source: packages/creact/src/runtime/scheduler.ts:1-60, packages/creact/src/runtime/run.ts:40-100.

Summary

The runtime engine is a small, self-contained React-like core. The fiber model provides the data structure, reconciliation provides the diff, and the state machine guarantees each fiber transitions through a well-defined lifecycle before effects can run. Together they form a predictable pipeline: createFiber → reconcile → commit → effects, with the scheduler batching state changes and instance.ts storing per-fiber hooks. Reading fiber.ts, reconcile.ts, state-machine.ts, run.ts, and instance.ts in that order gives a complete picture of how creact turns function calls into a working UI.

Related Pages

Related topics: Runtime Engine: Fiber Model, Reconciliation, and State Machine, Stores, Context, and Owner-Based Memory

Reactive System: Signals, Effects, and Dependency Tracking

Overview and Scope

The packages/creact/src/reactive/ directory implements the fine-grained reactivity layer of creact. It provides three primitive building blocks — signals for mutable state, selectors (computed/derived values) for read-only derivations, and effects for side-effecting reactions — together with a dependency-tracking subsystem and an *owner* hierarchy that manages lifecycle, teardown, and propagation.

The reactive layer is intentionally decoupled from the renderer. It exposes a synchronous, pull-based graph where reading a signal inside an effect registers the effect as a subscriber; writing the signal later schedules the effect to run again. The owner subsystem layers a parent/child tree on top of this graph so that nested reactions are disposed atomically.

Source: packages/creact/src/reactive/signal.ts:1-1, packages/creact/src/reactive/effect.ts:1-1, packages/creact/src/reactive/owner.ts:1-1.

Core Primitives: Signals and Selectors

A signal is a reactive cell holding a value. Reading it (signal.value) records the current subscriber, and writing it (signal.value = next) notifies every recorded subscriber. Internally, a signal stores its current value, a flag indicating whether listeners exist, and a set or linked list of dependent subscribers populated through the tracker.

Source: packages/creact/src/reactive/signal.ts:1-1.

A selector (computed) is a pure, read-only derivation built from other signals/selectors. It memoizes its result: the derivation function only re-runs when one of its tracked dependencies actually changes. If no upstream value has changed, accessing the selector returns the cached value and does not trigger downstream work. Selectors therefore break dependency chains and prevent redundant effect re-runs.

Source: packages/creact/src/reactive/selector.ts:1-1.

The relationship is:

Dependency Tracking

The tracking.ts module centralises the *currently collecting subscriber*. Before a reactive read (signal or selector access) executes, it pushes the current subscriber (the effect being constructed, or another selector) onto an internal listener slot; after the read returns, the recorded subscriber is added to the signal's dependency set.

Source: packages/creact/src/reactive/tracking.ts:1-1.

This indirection lets every read API share one mechanism. The pattern is roughly:

const prev = activeSubscriber;
activeSubscriber = currentEffect;
try {
  return signal.value;     // signal appends `currentEffect` to its deps
} finally {
  activeSubscriber = prev;
}

Source: packages/creact/src/reactive/tracking.ts:1-1.

Because the tracking uses a *push-then-pull* model — the effect pushes itself as the listener and pulls the signal value — dependencies are discovered lazily, only those actually touched during execution are subscribed. This avoids over-subscription and keeps invalidation cheap.

Effects and the Owner Hierarchy

An effect is a function executed once initially (to discover its dependencies), and re-executed whenever any of those dependencies change. Effects are scheduled rather than run synchronously to avoid inconsistent intermediate states and to batch multiple writes in the same tick.

Source: packages/creact/src/reactive/effect.ts:1-1.

The owner module gives the flat reactive graph a tree structure. An owner represents a scope (typically a component or a user-created scope). Effects and selectors created inside an owner are registered with that owner; when the owner is disposed, all child reactions are torn down together. Nested owners create nested lifecycles — a parent disposing does not affect siblings, and children cannot outlive their parent.

Source: packages/creact/src/reactive/owner.ts:1-1.

The current-owner.ts module maintains the "ambient" owner reference — the owner currently being constructed — so that every createSignal, createSelector, or createEffect call can self-register without the caller passing it explicitly. This is analogous to React's context stack or Vue's currentInstance.

Source: packages/creact/src/reactive/current-owner.ts:1-1.

Propagation and Teardown Workflow

The end-to-end flow of a write is:

sequenceDiagram
    participant User
    participant Signal
    participant Tracker
    participant Effect
    participant Owner

    User->>Tracker: begin tracking (push current effect)
    User->>Signal: read .value
    Signal->>Tracker: register effect as subscriber
    Note over Signal,Effect: Effect is now subscribed
    User->>Signal: write new value
    Signal->>Effect: notify (schedule)
    Effect->>Effect: re-run synchronously or on flush
    Owner->>Effect: dispose on teardown
    Effect->>Signal: unsubscribe from all deps

Source: packages/creact/src/reactive/signal.ts:1-1, packages/creact/src/reactive/effect.ts:1-1, packages/creact/src/reactive/tracking.ts:1-1, packages/creact/src/reactive/owner.ts:1-1.

When a component (or any scope) unmounts, the framework calls dispose() on its owner. The owner walks its child effects and selectors, invokes any user-supplied cleanup, and removes the effect from every signal's subscriber list. After this, the effect will never fire again even if its former dependencies mutate. This guarantees that DOM updates and other side effects cannot leak after teardown.

Source: packages/creact/src/reactive/owner.ts:1-1, packages/creact/src/reactive/effect.ts:1-1.

Design Notes

• Synchronous reads, batched writes. Reads register dependencies immediately; writes trigger notifications that may be queued and flushed together to coalesce re-runs.
• Dynamic dependencies. Because tracking happens at execution time, effects can branch on conditions and only subscribe to the dependencies they actually touch.
• Memory safety. The owner tree ensures no effect outlives its scope; the dependency set on each signal is cleaned when its subscribers dispose.
• Decoupling from rendering. The reactive layer knows nothing about the DOM or component tree; it only orchestrates *who depends on whom* and *when to re-run*. The renderer layer above it consumes effects to produce VDOM updates.

Source: packages/creact/src/reactive/signal.ts:1-1, packages/creact/src/reactive/selector.ts:1-1, packages/creact/src/reactive/effect.ts:1-1, packages/creact/src/reactive/tracking.ts:1-1, packages/creact/src/reactive/owner.ts:1-1, packages/creact/src/reactive/current-owner.ts:1-1.

Related Pages

Related topics: Introduction and Getting Started, Runtime Engine: Fiber Model, Reconciliation, and State Machine, Stores, Context, and Owner-Based Memory

JSX Runtime, Components, and Control Flow Primitives

Overview

The JSX runtime, components, and control flow primitives constitute the developer-facing surface of creact. They provide the syntactic bridge from JSX to creact's reactive node graph, define how user-authored components are composed and executed, and ship a small set of optimized built-ins for the most common dynamic UI patterns: lists, conditionals, and multi-way switches. Together, these modules let users write declarative, fine-grained reactive views without manually wiring up effects or DOM mutations. Source: packages/creact/src/jsx/index.ts, packages/creact/src/flow/for.ts, packages/creact/src/flow/show.ts, packages/creact/src/flow/switch.ts.

JSX Runtime Entry Points

The JSX runtime is split into three modules so that the same JSX syntax can be served in both development and production, and so that tooling can rely on stable entry points for tsconfig.json "jsxImportSource" and Babel's @jsxImportSource.

packages/creact/src/jsx/jsx-runtime.ts exposes the classic jsx, jsxs, Fragment, and jsxTemplate helpers used when TypeScript or Babel is configured with react-jsx / react-jsxdev against the creact import source. packages/creact/src/jsx/jsx-dev-runtime.ts mirrors this surface for development builds, providing jsxDEV so that JSX expressions retain debug-friendly shapes with key, ref, and source-location metadata. The aggregated re-exports and type definitions live in packages/creact/src/jsx/index.ts, which is the module users typically import via import { ... } from 'creact'. Source: packages/creact/src/jsx/index.ts, packages/creact/src/jsx/jsx-runtime.ts, packages/creact/src/jsx/jsx-dev-runtime.ts.

The runtime functions do not create DOM eagerly; they construct lightweight element descriptors. Hosting these descriptors into reactive scopes is what enables fine-grained updates later on. Source: packages/creact/src/jsx/jsx-runtime.ts.

Components

User components are plain functions whose body is invoked once during composition. Unlike diffing-based frameworks, creact does not re-run the component body when props change. Instead, the reactive expressions inside the component re-evaluate independently when the signals they read change. A component returns a JSX node (typically via the runtime helpers), and creact reconciles the reactive graph rooted at that return value. Source: packages/creact/src/jsx/index.ts, packages/creact/src/jsx/jsx-runtime.ts.

This model has two practical consequences for authors: functions stay cheap because they are not re-invoked, and side effects must be wrapped in reactive primitives so they only run on real dependency changes rather than every parent re-render. Component children are passed as a special children prop, which the runtime ultimately hosts into the returned element so that nested reactivity composes naturally.

Control Flow Primitives

creact ships three built-in families of control flow components under packages/creact/src/flow/. They are preferable to naïve .map(...) and ternary expressions because they preserve stable identities for items and branches across updates, which keeps DOM and effect bookkeeping cheap. Source: packages/creact/src/flow/for.ts, packages/creact/src/flow/show.ts, packages/creact/src/flow/switch.ts.

Lists with `<For>`

for.ts exports For, which iterates over an array-like source by tracking each item's identity (typically by a user-provided each accessor and the array reference itself). <For each={list} fallback={<Empty/>}>{(item, index) => ...}</For> reuses existing nodes for items that survive across updates and inserts or removes nodes only at the boundaries where the array actually changed, rather than rebuilding the list on every mutation. Source: packages/creact/src/flow/for.ts.

Conditional with `<Show>`

show.ts provides Show for single-branch conditionals. <Show when={signal()} fallback={...}>{value => ...}</Show> mounts its children when the condition is truthy, optionally receiving the unwrapped value as the callback argument, and swaps in fallback otherwise. Because when is read through creact's reactive accessor, the conditional re-evaluates automatically when the underlying signal flips, without re-running any enclosing component. Source: packages/creact/src/flow/show.ts.

Multi-Branch with `<Switch>` / `<Match>`

swith.ts (and matching Match) handles N-way conditionals analogous to a chain of <Show when=...> calls but more efficient when exactly one branch must be active. Consumers wrap ordered <Match when={...}>...</Match> children inside a <Switch fallback={...}> parent; creact picks the first matching branch and mounts only that subtree. Source: packages/creact/src/flow/switch.ts.

Relationship Between the Three Layers

At runtime, a user's JSX is first lowered into element descriptors by the JSX runtime. Component function bodies wrap reactive expression nodes into the returned descriptor. Control flow primitives are themselves just components that own their own reactive bookkeeping, so they slot in wherever any other component would. The boundary that matters most is that the JSX runtime is *not* a reconciler — it only describes intent. The actual updating behavior is driven by reactive primitives and the control flow components that know how to handle common diff shapes efficiently. Source: packages/creact/src/jsx/jsx-runtime.ts, packages/creact/src/flow/for.ts, packages/creact/src/flow/show.ts, packages/creact/src/flow/switch.ts.

Compact API Map

Related Pages

Related topics: Runtime Engine: Fiber Model, Reconciliation, and State Machine, Reactive System: Signals, Effects, and Dependency Tracking, AI Integration with Claude and Cloud Deployment

Stores, Context, and Owner-Based Memory

The Memory System in creact unifies three cooperating primitives — Stores, Context, and Owner-Based Memory — to give reactive components a deterministic way to share, scope, and dispose of state. Together they replace the ad-hoc globals and prop-drilling patterns typical of component frameworks with a single owner-tracked memory model. The architecture treats a Store as the unit of durable data, a Context as the propagation channel between producers and consumers, and the Owner as the disposer that ties a memory lifetime to the component that requested it. Source: apps/website/src/i18n/resources/en/docs/architecture/memory_system.json:1- summarizes this design at the documentation level.

Stores: Reactive State Containers

A Store is a reactive container holding a typed value plus the metadata needed to subscribe to its changes. It is implemented in the store module and is the canonical place where application state lives, independent of any particular component tree. Stores expose a minimal surface — read access, write access, and change subscription — so they can be passed through context, returned from hooks, or stored on an owner without losing reactivity. Source: packages/creact/src/store/store.ts:1-.

Because a store is just a value envelope, it composes naturally with the rest of the reactive system: any signal, ref, or computed value nested inside it is tracked under the active Owner, which means memory cleanup flows through the store automatically when the owning component unmounts. Source: packages/creact/src/reactive/owner.ts:1-.

Context: Provid[packages/creact/src/reactive/current-owner.ts](https://github.com/creact-labs/creact/blob/main/packages/creact/src/reactive/current-owner.ts)

• packages/creact/src/runtime/memory.ts

ing and Resolving Values

Context is the primitive a component uses to publish a value to its descendants and consume the nearest published value during render. Defined in primitives/context.ts, it pairs a provider (used by an ancestor component, often wrapping a Store) with a consumer (used by any descendant to read it). Context is the only sanctioned way to pass a Store across component boundaries without prop drilling. Source: packages/creact/src/primitives/context.ts:1-.

The provider-consumer relationship is resolved dynamically at render time: when a consumer runs inside a reactive scope, the renderer walks up the current owner chain via current-owner.ts to locate the closest provider and binds the store to that scope. This means re-parenting a subtree automatically redirects reads to the new nearest provider, without consumers having to be rewritten. Source: packages/creact/src/reactive/current-owner.ts:1-.

flowchart TD
    A[Root Owner] --> B[Provider: Store X]
    B --> C[Consumer reads Store X]
    B --> D[Provider: Store Y]
    D --> E[Consumer reads Store Y]
    C -.schedules.-> F[Reactive Runtime]
    E -.schedules.-> F
    F --> G[Memory: dispose on unmount]

Owner-Based Memory: Scoped Lifetime

The Owner is the bookkeeping object that records every memory subscription a component creates while it is rendering. Defined in reactive/owner.ts, an owner is automatically constructed on each reactive entry (function component, effect, or memo) and is linked to its parent owner through current-owner.ts, forming a tree that mirrors the component tree. Source: packages/creact/src/reactive/owner.ts:1-., Source: packages/creact/src/reactive/current-owner.ts:1-

The runtime/memory.ts module is the executor that operations consult: whenever a store subscription, ref, effect, or context binding is registered, it calls the memory runtime to attach that record to the active Owner. When the owner is disposed (because its component is removed or its effect is re-run), the runtime walks the recorded list and tears every entry down in reverse order — closing subscriptions, releasing callbacks, and allowing garbage collection of the captured values. Source: packages/creact/src/runtime/memory.ts:1-.

This owner-tracked model is what makes the memory system "automatic": developers create stores and effects freely, and they are guaranteed to be cleaned up exactly once, exactly when the component that owns them leaves the tree. The documentation confirms this is the intended contract for the architecture. Source: apps/website/src/i18n/resources/en/docs/architecture/memory_system.json:1-

End-to-End Flow

A typical lifecycle combining all three primitives works as follows. A top-level component creates a Store, wraps it in a Context.Provider, and renders. Each descendant uses the context hook to obtain the store; the consumer reads the value and, by virtue of executing under the current owner, registers a subscription in runtime/memory.ts. If the top-level component unmounts, its owner is disposed, and the runtime tears down every store subscription recorded under it, reclaiming memory deterministically. Source: packages/creact/src/store/store.ts:1-, Source: packages/creact/src/primitives/context.ts:1-, Source: packages/creact/src/runtime/memory.ts:1-

Because stores, contexts, and owners are layered concerns — data, transport, lifetime — the API stays small while the memory guarantees remain uniform across components, effects, and external integrations.

[packages/creact/src/store/store.ts](https://github.com/creact-labs/creact/blob/main/packages/creact/src/store/store.ts)

• packages/creact/src/primitives/context.ts
• packages/creact/src/reactive/owner.ts

Related Pages

Related topics: Introduction and Getting Started, AI Integration with Claude and Cloud Deployment

CLI Tooling, Watch Mode, and Testing Utilities

Purpose and Scope

The creact framework ships a developer-facing toolchain distributed across two workspaces: the CLI tooling under packages/creact/src/ and the testing utilities under packages/testing/src/. Together they cover the "author → iterate → validate" loop. The CLI drives project-level commands such as running the development server and performing type checking, while the testing package provides low-level helpers that mount creact components in test environments.

This page documents the structure of these modules, the role each file plays, and how they cooperate to deliver watch-mode development and component rendering tests.

CLI Module Architecture

The CLI is intentionally factored into four small modules rather than a single file. This keeps the entry surface narrow and lets each concern evolve independently.

• cli.ts is the entry point. It parses process.argv, resolves the requested subcommand, and dispatches control to the matching handler.
• cli-main.ts hosts the implementations of the primary commands (development server, build) and the watch loop used during development.
• cli-typecheck.ts isolates type-checking logic so it can be invoked standalone or as part of a wider pipeline.
• cli-logger.ts centralizes the formatting of CLI output, ensuring that messages from different commands share a consistent style.

flowchart LR
    User([Developer]) --> Argv[process.argv]
    Argv --> Entry[cli.ts]
    Entry --> Main[cli-main.ts]
    Entry --> Typecheck[cli-typecheck.ts]
    Main --> Logger[cli-logger.ts]
    Typecheck --> Logger
    Main --> Watcher[(File Watcher)]

This separation lets type checking and logging evolve without touching command logic, and lets command bodies grow without the entry module growing in lockstep.

Source: packages/creact/src/cli.ts:1-200 Source: packages/creact/src/cli-main.ts:1-200 Source: packages/creact/src/cli-typecheck.ts:1-200 Source: packages/creact/src/cli-logger.ts:1-200

Watch Mode and Development Workflow

Watch mode is not implemented as a standalone file; it is part of the development command path inside cli-main.ts. When the developer starts the development command, the CLI initializes a file watcher and enters a loop that reacts to filesystem events. Each iteration typically performs four steps:

1. Detect changed files via the watcher.
2. Re-run the relevant compiler or transform on those files.
3. Optionally invoke cli-typecheck.ts to surface incremental type errors.
4. Emit user-facing status through cli-logger.ts.

Because the logger is shared across all CLI commands, watch-loop output follows exactly the same conventions as one-shot commands. Keeping the watch loop inside cli-main.ts rather than promoting it to a separate file means it can reuse the command's own configuration and pipeline without redundant setup, and the type checker can be plugged in as a stage of the same workflow.

Source: packages/creact/src/cli-main.ts:1-200 Source: packages/creact/src/cli-typecheck.ts:1-200 Source: packages/creact/src/cli-logger.ts:1-200

Testing Utilities

The testing package occupies its own workspace and exposes a focused API for rendering creact components in isolation. Its public surface is defined by packages/testing/src/index.ts, which re-exports the helpers developers import in their test files.

The core implementation lives in packages/testing/src/render-test.ts. This module provides the render function, which mounts a creact component tree into a host environment (typically a DOM-like test container) and returns inspection handles. Tests use those handles to query the rendered output, trigger updates, or unmount the tree.

Keeping the render implementation in its own module — and the public re-exports in index.ts — lets the testing package add additional helpers (for example, server-side rendering or snapshot utilities) without bloating the entry module. Test files import only what they need, and the underlying implementation can change without affecting import sites.

Source: packages/testing/src/index.ts:1-200 Source: packages/testing/src/render-test.ts:1-200

How the Pieces Fit Together

The CLI and testing packages do not share code directly, but they share architectural conventions. Both favor small, single-purpose modules; both isolate the public entry point from the implementation; and both rely on a clear separation between the exported API and the internal helpers. The CLI focuses on orchestrating the whole project (compile, watch, type-check), while the testing package focuses on isolating individual components for verification.

This separation keeps the developer experience consistent — the CLI is where projects start and iterate, and the testing utilities are where individual components are validated — without coupling the two concerns.

Source: packages/creact/src/cli.ts:1-200 Source: packages/testing/src/index.ts:1-200

Summary

In summary, creact's CLI tooling is organized around cli.ts (entry and dispatch), cli-main.ts (command bodies and the watch loop), cli-typecheck.ts (type checking), and cli-logger.ts (shared output formatting). The watch-mode lifecycle lives in cli-main.ts and reuses the shared logger and optional type checker. The testing package provides rendering utilities through index.ts (re-exports) and render-test.ts (the render implementation). Together these modules form a cohesive developer toolchain for authoring, iterating on, and verifying creact components.

Related Pages

Related topics: Stores, Context, and Owner-Based Memory, Runtime Boundaries, Error Handling, and Operations

AI Integration with Claude and Cloud Deployment

Overview and Scope

The hero-fleet example application is a demonstration workspace within the creact monorepo that showcases how AI-driven code generation composes with cloud infrastructure tooling. It pairs Anthropic's Claude model with AWS deployment utilities to produce and publish generated artifacts (HTML pages, web sites, channel payloads) directly from a React/creact front-end.

Source: libs/examples/apps/hero-fleet/src/app/index.tsx:1-40

The application is not a production system; it is a reference implementation illustrating the boundaries between three concerns: (1) invoking a large language model, (2) transforming model output into deployable assets, and (3) pushing those assets to a cloud provider.

Source: libs/examples/apps/hero-fleet/src/components/claude/index.tsx:1-30

Component Layout

The front-end is decomposed into five feature components, each owning one capability. The root app component coordinates their composition and shared state.

Source: libs/examples/apps/hero-fleet/src/app/index.tsx:20-80

This separation lets each integration be swapped independently — for example, replacing Claude with another provider only requires changes inside claude/index.tsx, while aws/index.tsx remains untouched.

Source: libs/examples/apps/hero-fleet/src/components/aws/index.tsx:1-40

Claude Integration

The claude component encapsulates the model invocation. It owns the request payload, the streaming or batched response handling, and any client-side post-processing before handing the text back to the rest of the app.

Source: libs/examples/apps/hero-fleet/src/components/claude/index.tsx:30-120

Downstream components treat the Claude wrapper as a pure producer of text: they receive a string (or token stream) and decide what to do with it. The generate-html consumer interprets Claude output as markup, while web-site consumes a richer structure that may include titles, sections, and assets.

Source: libs/examples/apps/hero-fleet/src/components/generate-html/index.tsx:1-60

Source: libs/examples/apps/hero-fleet/src/components/web-site/index.tsx:1-60

The channel component sits between Claude and the generators, acting as a normalized envelope so that any future input source (not just Claude) can feed the same downstream pipeline.

Source: libs/examples/apps/hero-fleet/src/components/channel/index.tsx:1-50

Cloud Deployment via AWS

The aws component is responsible for shipping the generated assets to AWS. It accepts a finished artifact from generate-html or web-site, uploads it to the configured storage / hosting target, and returns a deployment handle (typically a URL or ARN) that the UI can display or hand to subsequent steps.

Source: libs/examples/apps/hero-fleet/src/components/aws/index.tsx:40-140

Deployment configuration (bucket names, region, credentials) is expected to be supplied at the call site rather than hard-coded inside the component, keeping aws/index.tsx reusable across environments.

Source: libs/examples/apps/hero-fleet/src/components/aws/index.tsx:60-90

End-to-End Workflow

A typical user interaction follows this sequence:

1. The app collects the user's intent and forwards it through the channel envelope.
2. claude invokes the model and returns generated text.
3. generate-html or web-site shapes that text into a concrete artifact.
4. aws uploads the artifact and returns a deployment reference.
5. The app renders the reference back to the user.

flowchart LR
    A[User Intent] --> B[channel]
    B --> C[claude]
    C --> D[generate-html / web-site]
    D --> E[aws]
    E --> F[Deployed URL]
    F --> G[UI Result]

Source: libs/examples/apps/hero-fleet/src/app/index.tsx:40-100

Source: libs/examples/apps/hero-fleet/src/components/channel/index.tsx:50-80

Design Observations

• Each feature component exposes a narrow, replaceable surface, which is the principal pedagogical point of hero-fleet.
• The Claude boundary and the AWS boundary are intentionally distant in the component tree: no component other than app knows about both, which keeps responsibilities clean.
• Credentials, prompts, and bucket configuration are all expected at the call site, leaving the example components free of secrets and environment-specific values.

Source: libs/examples/apps/hero-fleet/src/components/claude/index.tsx:120-160

Source: libs/examples/apps/hero-fleet/src/components/aws/index.tsx:140-180

Related Pages

Related topics: Runtime Engine: Fiber Model, Reconciliation, and State Machine, JSX Runtime, Components, and Control Flow Primitives, AI Integration with Claude and Cloud Deployment

Runtime Boundaries, Error Handling, and Operations

This page describes how the creact runtime defines its execution boundaries, isolates and surfaces errors, and exposes the core operations consumed by user code and internal subsystems. The content is bounded to the runtime package, the flow error boundary, shared type definitions, and the architecture documentation entry that frames the topic. Source: apps/website/src/i18n/resources/en/docs/architecture/runtime_boundaries.json:1-1

1. Runtime Boundaries and the Async Mutex

The runtime is created through a single factory and operates as the boundary between user code (signals, computations, side effects) and the scheduling/notification machinery underneath. createRuntime returns the public surface that components and primitives interact with, while keeping mutation, subscription, and disposal private to the package. Source: packages/creact/src/runtime/create-runtime.ts:1-1

Concurrency within the runtime is regulated by an async mutex that serializes access to shared mutable state. Because computations and effects can be scheduled from microtasks, timers, and async sources, the mutex guarantees that one logical unit of work holds the runtime state at a time, preventing torn reads and inconsistent observers. Source: packages/creact/src/runtime/async-mutex.ts:1-1

The mutex exposes a minimal contract built around three operations: acquire() resolves when the caller obtains exclusive access, release() returns the lock and wakes the next waiter, and runExclusive(fn) is a convenience wrapper that acquires the lock, runs the supplied function, and releases it deterministically even when the function throws. This contract keeps "run this work inside the runtime" an explicit decision rather than an implicit one, which is the core of the boundary model.

2. Error Handling via the Error Boundary

Component-level failures are isolated by the flow error boundary, a control-flow primitive distinct from the runtime mutex. The boundary wraps a subtree, catches thrown values during render or effect execution, and renders a fallback instead of propagating the failure upward. Source: packages/creact/src/flow/error-boundary.ts:1-1

Operationally, the boundary maintains a "did catch" flag that is reset on each commit and set when an error is captured. Children are rendered conditionally on this flag: the boundary renders its children; if a child throws (synchronously during render, or asynchronously inside an effect scheduled by the boundary) the throw is intercepted; the flag is set, and the fallback node is rendered on the next pass; a reset callback exposed by the boundary clears the flag so the children can be retried.

This pattern keeps the boundary's contract synchronous from the consumer's perspective while still tolerating async throws, because the runtime's mutex guarantees that the recovery path observes a consistent state. Source: packages/creact/src/runtime/async-mutex.ts:1-1

3. Core Operations: Equality and Shared Types

Equality is treated as an explicit runtime operation rather than an implicit ===. The plainObjectsEqual helper compares two records key-by-key, recursing into nested plain objects and short-circuiting on the first mismatch. It is used by reactive primitives that need to decide whether a value change should propagate to subscribers, and it deliberately avoids walking class instances or functions so that referential identity is preserved for non-plain values. Source: packages/creact/src/runtime/plain-objects-equal.ts:1-1

The shared type module defines the vocabulary that ties these pieces together. It exposes the runtime shape, including the operation handles returned by createRuntime; the error boundary props and the fallback node type; and the discriminated shape of values flowing through the system (plain objects, primitives, signals, computations). Source: packages/creact/src/types.ts:1-1

By centralizing the types, the runtime, the equality helper, and the boundary all speak the same language about what constitutes a "value", a "node", and an "operation", which prevents drift between the scheduler, the recovery path, and the public API.

4. How the Pieces Compose

The diagram below shows how a user operation flows from the public API through the boundary, into the runtime, and back out as a notification or a recovered render.

flowchart TD
    A[User code: read/write/compute] --> B[createRuntime surface]
    B --> C{async-mutex acquire}
    C --> D[Mutate internal state]
    D --> E[plainObjectsEqual vs last snapshot]
    E -- changed --> F[Schedule subscribers]
    E -- unchanged --> G[Skip]
    F --> H[Release lock]
    G --> H
    H --> I[Notify effect / boundary]
    I -- thrown --> J[error-boundary fallback]
    I -- ok --> K[Commit]

Two boundaries are visible: the mutex, which separates "inside the runtime" from "outside", and the error boundary, which separates "healthy subtree" from "recovered subtree". Equality sits between them as the gate that decides whether a state change is worth crossing the notification boundary. Source: packages/creact/src/runtime/plain-objects-equal.ts:1-1

Together, these files describe a runtime whose discipline is "one owner of state, one place to recover from failure, one definition of equality". Every other module in creact depends on this discipline rather than re-implementing it, which is why the runtime boundary, error boundary, and equality helper live in dedicated files and are wired together through the shared type contract.

Doramagic Pitfall Log

Found 6 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Capability evidence risk - Capability evidence risk requires verification.

1. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/creact-labs/creact

2. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/creact-labs/creact

3. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/creact-labs/creact

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/creact-labs/creact

5. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/creact-labs/creact

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/creact-labs/creact

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using creact with real data or production workflows.

• Capability evidence risk requires verification - GitHub / issue