@adamwirda/reactive-dom

A tiny reactive DOM library built from scratch, without Virtual DOM.

This package provides:

• A minimal reactive state system
• A component factory that renders directly to real DOM
• Fine-grained reactivity (no full re-render)

⚠️ Experimental / learning-oriented project
Built to understand how modern frontend frameworks work internally.

✨ Features

• ⚡ Direct DOM manipulation (no Virtual DOM)
• 🧠 Fine-grained reactivity
• 📦 Zero dependencies
• 🧩 Fully typed with TypeScript
• 🔍 Simple mental model

📦 Installation

npm install @adamwirda/reactive-dom

or

pnpm add @adamwirda/reactive-dom

🚀 Quick Start

Create reactive state

import { createState } from '@adamwirda/reactive-dom'

const count = createState(0)

Define a component

import { defineComponent, render, createState } from '@adamwirda/reactive-dom'

const count = createState(0)

const Counter = defineComponent({
  element: 'button',
  bindEvent: {
    click: () => count.set(count.value + 1)
  },
  children: [
    () => `Count: ${count.value}`
  ]
})

Render to DOM

render(Counter(), document.body)

🧠 Reactivity Model

Reactivity is dependency-based, not re-render based.

import { trackState } from '@adamwirda/reactive-dom'

trackState(() => {
  console.log(count.value)
})

• Reading state.value registers a dependency
• Calling state.set() triggers subscribed effects

🧩 Component API

defineComponent<Props>()

const Text = defineComponent<{ message: string }>({
  element: 'span',
  children: [
    props => props.message
  ]
})

Usage:

Text({ message: 'Hello' })

Component without props

const Box = defineComponent({
  element: 'div'
})

Box()

🔗 Children Types

A component child can be:

• string
• Node
• another component
• a reactive function

children: [
  'static text',
  () => count.value,
  OtherComponent
]

If a child function returns a Node, the DOM subtree is replaced reactively.

🎨 Reactive Attributes

attrs: {
  class: () => count.value > 5 ? 'big' : 'small'
}

Attributes update automatically when dependencies change.

🔔 Event Handling

bindEvent: {
  click: (e, props) => {
    console.log('clicked')
  }
}

🛠 API Reference

createState<T>(initialValue)

const state = createState(0)

state.value        // get
state.set(1)       // set
state.subs(fn)     // subscribe

trackState(fn)

Registers a reactive effect.

trackState(() => {
  console.log(state.value)
})

render(node, target)

render(component(), document.body)

⚠️ Limitations

• No Virtual DOM
• No diffing algorithm
• No SSR
• No lifecycle hooks (yet)

This library is intended for learning, experimentation, and small demos.

🧠 Why this exists

This project was built to:

• Understand how frameworks like Vue, Solid, and Svelte work internally
• Explore fine-grained reactivity
• Practice framework-level TypeScript design

📜 License

MIT

🙌 Author

Adam Wirda
Built with curiosity and caffeine ☕
Feel free to fork, break, or improve.