Fabric

A lightweight frontend UI runtime built from scratch with TypeScript.

Fabric is an experimental frontend runtime focused on understanding and implementing the core concepts behind modern UI libraries, including:

• Virtual DOM.
• Components.
• State.
• Effects.
• Reconciliation.
• Scheduling.
• DOM updates.

Fabric is not a React clone. It is an independent runtime built from first principles.

Features

Fabric currently supports:

• Virtual DOM.
• createElement().
• JSX.
• Automatic JSX runtime.
• Function components.
• Props.
• useState().
• useEffect().
• Effect cleanup.
• DOM events.
• Reconciliation.
• Keyed reconciliation.
• DOM property updates.
• Update scheduling and batching.
• Component lifecycle handling.
• TypeScript.
• Automated tests.

Runtime Overview

At a high level, Fabric works like this:

JSX / createElement()
        ↓
   JSX Runtime
        ↓
      VNode
        ↓
   Components
        ↓
 State / Effects
        ↓
    Scheduler
        ↓
 Reconciliation
        ↓
       DOM

For JSX, TypeScript uses Fabric's automatic JSX runtime:

JSX
 ↓
TypeScript JSX transform
 ↓
@siddh-dev/fabric/jsx-runtime
 ↓
createElement()
 ↓
VNode
 ↓
Reconciliation
 ↓
DOM

When state changes:

setState()
    ↓
schedule update
    ↓
component re-renders
    ↓
new VNode
    ↓
reconciliation
    ↓
DOM update

Quick Example

import {
    createRoot,
    useState
} from "@siddh-dev/fabric";

function Counter() {
    const [count, setCount] = useState(0);

    return (
        <div>
            <h1>Fabric</h1>

            <p>
                Count: {count}
            </p>

            <button onClick={() => setCount(count + 1)}>
                Increment
            </button>
        </div>
    );
}

const container = document.getElementById("app");

if (container === null) {
    throw new Error("App container not found.");
}

createRoot(container).render(
    <Counter />
);

Fabric supports the automatic JSX runtime, so you do not need to import jsx() manually.

For TypeScript consumers, configure JSX like this:

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "@siddh-dev/fabric"
  }
}

The "jsxImportSource": "@siddh-dev/fabric" option tells TypeScript to use Fabric's JSX runtime.

Application code does not need to manually import jsx().

Installation

Using pnpm:

pnpm add @siddh-dev/fabric

Using npm:

npm install @siddh-dev/fabric

For development setup and TypeScript configuration, see the Installation Guide.

Documentation

The complete documentation is available in the docs/ directory.

Getting Started

• Installation
• Quick Start

Concepts

• Architecture
• Virtual DOM
• Components
• Props
• State
• Effects

Runtime

• JSX
• Events
• Reconciliation
• Keyed Reconciliation
• Scheduler
• DOM

API

• Public API

Development

• Testing
• Packaging
• Contributing

Project

• Roadmap

Development

Clone the repository:

git clone <repository-url>
cd Fabric

Install dependencies:

pnpm install

Start development mode:

pnpm dev

Run tests in watch mode:

pnpm test

Run the test suite once:

pnpm test:run

Run type checking:

pnpm check

Build the package:

pnpm build

Clean generated build output:

pnpm clean

Testing

Fabric uses:

• Vitest.
• jsdom.
• TypeScript.

Run the complete test suite:

pnpm test:run

Tests cover areas including:

• VNode creation.
• JSX.
• Components.
• Props.
• State.
• Effects.
• Effect cleanup.
• Events.
• Reconciliation.
• Keyed reconciliation.
• Scheduler behavior.
• Root rendering.
• DOM updates.

Project Structure

Fabric/
├── src/
│   ├── core/
│   │   ├── component/
│   │   ├── hooks/
│   │   ├── jsx/
│   │   ├── scheduler/
│   │   └── vnode/
│   │
│   ├── dom/
│   │   ├── DOMProperties.ts
│   │   ├── EventSystem.ts
│   │   └── Reconciler.ts
│   │
│   ├── runtime/
│   │   └── createRoot.ts
│   │
│   └── index.ts
│
├── tests/
├── docs/
├── index.html
├── package.json
├── tsconfig.json
├── tests/tsconfig.json
└── vitest.config.ts

The runtime is broadly organized as:

VNode
  ↓
Components / Hooks
  ↓
Scheduler
  ↓
Reconciler
  ↓
DOM

V0.1

The initial goal of Fabric is to establish a small but functional frontend runtime.

V0.1 focuses on:

• VNodes.
• JSX.
• Automatic JSX runtime.
• Function components.
• Props.
• State.
• Effects.
• Effect cleanup.
• Events.
• Reconciliation.
• Keyed reconciliation.
• Scheduler and batching.
• Basic DOM operations.
• Public API.
• Tests.
• Packaging.
• Documentation.

The V0.1 scope is intentionally limited. The goal is to establish a reliable foundation rather than implement every possible framework feature.

Future

Possible future areas include:

• Context.
• Additional hooks.
• Refs.
• Fragments.
• Memoization.
• Portals.
• Error boundaries.
• Suspense-like rendering.
• Advanced scheduling.
• Concurrent rendering.
• Server-side rendering.
• Hydration.
• Developer tools.

These are future possibilities, not commitments to the current V0.1 scope.

See the Roadmap for more information.

Contributing

Contributions are welcome.

Before contributing, read the Contributing Guide.

For development information, see:

• Testing
• Packaging
• Architecture

Good contributions can include:

• Bug fixes.
• Regression tests.
• Documentation improvements.
• Runtime improvements.
• Refactors that improve clarity.
• Performance improvements supported by measurements.
• Better package validation.

Please keep changes focused and aligned with Fabric's architecture.

License

MIT