🌿 KitJS

A lightweight HTML-first JavaScript framework for developers who want the web to stay simple reactive and seamlessly enhanced on the server

✨ Features

⚡ Lightweight and fast with minimal runtime 💡 HTML-first meaning logic and state live directly in your markup 🔄 Reactive by design keeping DOM and data in sync automatically 🌐 SSR-ready and works seamlessly with server-rendered pages 🔒 Fully secure and compatible with Content Security Policy 🧩 No build tools required simply include a <script> tag

⚡ Quick Start

Include KitJS from a CDN

<script src="https://unpkg.com/@kitmodule/kitjs"></script>

Or install using npm

npm install @kitmodule/kitjs

Your first reactive component

<div data-kit-scope="counter">
  <button data-kit-click="decrement()">-</button>
  <span data-kit-bind="count"></span>
  <button data-kit-click="increment()">+</button>
</div>

<script>
Kit.define("counter", {
  count: 0,
  increment() { this.count++ },
  decrement() { this.count-- },
})
</script>

✅ No build tools ✅ No virtual DOM ✅ HTML that reacts naturally

🧩 Core Directives

| Purpose | Directive or Syntax | Example | | -------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------- | | Define reactive scope | data-kit-scope="$alias" for unique or data-kit-scope="name" for shared | <div data-kit-scope="$todo"> | | Bind text or expression | data-kit-bind | <span data-kit-bind="user.name"> | | Two-way input binding | data-kit-model | <input data-kit-model="email"> | | One-time DOM to state sync | data-kit-sync | <input value="John" data-kit-sync="user.name"> | | Event binding | data-kit-click or data-kit-event | <button data-kit-click="save()"> | | Keyboard events | data-kit-keydown:enter | <input data-kit-keydown:enter="submit()"> | | Conditional display | data-kit-show | <div data-kit-show="open"> | | Dynamic class binding | data-kit-class | <div data-kit-class="active ? 'bg-red' : 'bg-green'"> | | Reactive styles | data-kit-style | <p data-kit-style="color: done ? 'green':'red'"> | | Loop or repeat | data-kit-for | <li data-kit-for="todo of todos"> |

💡 Example Todo List

<div data-kit-scope="todo">
  <h2>Todo List</h2>
  <input data-kit-model="newTask" data-kit-keydown:enter="add()">
  <button data-kit-click="add()">Add</button>

  <ul>
    <li data-kit-for="(item, i) of todos">
      <input type="checkbox" data-kit-model="item.completed">
      <span data-kit-bind="item.text"></span>
      <button data-kit-click="remove(i)">x</button>
    </li>
  </ul>

  <div style="padding:12px 24px; text-align:left;">
    <span data-kit-bind="completeds">0</span>
    <span>/</span>
    <span data-kit-bind="text:todos.length">0</span>
    completed tasks
  </div>
</div>

<script>
Kit.define("todo", {
  newTask: "",
  todos: [],
  add() {
    if (!this.newTask.trim()) return
    this.todos.unshift({ 
         id: Math.random(),
        text: this.newTask, 
        completed: false
         })
    this.newTask = ""
  },
  remove(i) { this.todos.splice(i, 1) },
  get completeds() {
    return this.todos.filter(todo => todo.completed).length
  }
})
</script>

🔁 One-time Sync

data-kit-sync hydrates your state from existing DOM values making it ideal for server-rendered or static pages.

<div data-kit-scope="$user">
  <input value="Alice" data-kit-sync="user.name">
  <p>Hello, <span data-kit-bind="user.name"></span>!</p>
</div>

<script>
Kit.define("user", { user: { name: "" } })
</script>

The user.name value becomes "Alice" automatically when the page loads.

⚙️ Element Spine

Each DOM element has a reactive spine exposing scope state and ownership.

| Property | Description | | ------------------------ | ----------------------------------- | | $get(name) | Get directive value | | $set(name, value) | Set directive value | | $value | Get or set element content or value | | $component | Owning component instance | | $state | Reactive state object | | $find(name) | Query within current scope | | $dispatch(type, event) | Trigger event handlers manually |

const input = document.querySelector("input[data-kit-model='name']")
console.log(input.$state.name)

🧠 Event System

KitJS supports expressive event syntax with modifiers and variants

<input data-kit-keydown:enter:stop:prevent="submit()">
<button data-kit-click:once="save()">Save</button>

| Modifier | Description | | ---------------------- | -------------------------------------------- | | once | Run once and remove listener | | stop | Call stopPropagation | | prevent | Call preventDefault | | debounce:300 | Delay execution by 300 milliseconds | | throttle:500 | Limit execution to once per 500 milliseconds | | outside | Trigger when clicking outside element | | window or document | Attach listener globally |

<div data-kit-scope="$modal">
  <div data-kit-show="open">Modal content</div>
  <button data-kit-click="open = true">Open</button>
  <div data-kit-click:outside="open = false"></div>
</div>

🧩 Built-in Utilities

el.$dataset    // Reactive directive dataset
el.$owner()    // Nearest component root
el.$find('bind') // Query directive inside scope

These utilities make KitJS introspective and hackable.

🌐 SSR and Progressive Enhancement

<div data-kit-scope="$profile">
  <h2 data-kit-bind="name">Alice</h2>
  <input value="Alice" data-kit-sync="name">
</div>

<script>
Kit.define("profile", { name: "" })
</script>

On hydration state automatically picks up DOM data with no mismatches and no re-rendering.

Benefits

• Instant state recovery
• Zero hydration errors
• Works perfectly for static or server-rendered pages

🌱 When to Use KitJS

KitJS is not a competitor to React or Vue and it is for developers who want HTML to stay alive.

Use it when you want to:

• Build small reactive components directly in HTML
• Enhance existing pages or templates
• Create embeddable widgets or demos
• Prototype quickly without a build step
• Keep your stack framework-free

Think of it as HTML with a pulse

💭 Philosophy

KitJS is not built to compete. It reminds us that the web can be simple reactive and human. HTML and JavaScript can live as one.

KitJS is your quiet companion for reactive HTML.

🧩 Examples

| Example | Description | | ------------------------------------------------------- | ------------------------ | | Counter | Minimal state and events | | Todo List | Loops and bindings | | Dropdown | Conditional visibility | | Tags Input | Dynamic list editing |

💖 Funding

If you love KitJS and want to support its development, you can sponsor or buy me a coffee ☕

🧪 License

Released under the MIT License © 2025 Huỳnh Nhân Quốc · Open Source @Kit Module