IO-Reactive

A lightweight and fast next-generation reactive UI library for the web. Supports directives, islands architecture, high performance, and minimal bundle size.

Advantages

• Minimal size: <100kB (gzip)
• High performance: optimized rendering and updates
• Directives: declarative binding, validation, masks, custom behaviors
• Islands architecture: partial hydration, SSR, lazy component loading
• Compatibility: easily integrates into existing projects
• TypeScript-first: strict typing, JSDoc

Installation

npm install io-reactive

Quick Start

Minimal Example

import { IO, tag } from 'io-reactive';

// Create a simple component
function MyApp() {
    return new IO(tag.DIV, {
        text: 'Hello, world!',
        classList: ['app-container'],
    });
}

// Initialize the app
const root = document.getElementById('app');
if (root) {
    const app = MyApp();
    root.appendChild(app.render());
}

Interactive Example with State

import { IO, tag } from 'io-reactive';

function CounterApp() {
    const io = new IO(tag.DIV);

    // Use built-in state
    const [count, setCount] = io.state<number>(0);

    io.components = [
        () =>
            new IO(tag.H1, {
                text: () => `Counter: ${count()}`,
            }),
        () =>
            new IO(tag.BUTTON, {
                text: 'Increment',
                events: {
                    click: () => setCount(count() + 1),
                },
            }),
    ];

    return io;
}

// Run the app
document.addEventListener('DOMContentLoaded', () => {
    const root = document.getElementById('app');
    if (root) {
        root.appendChild(CounterApp().render());
    }
});

Core Features

1. Islands Architecture

Revolutionary technology for web optimization. Static content is rendered on the server without JavaScript, and interactive "islands" are hydrated as needed.

Static Components

// Static component (SSR, no JS on client)
const header = IO.static('header', {
    classList: ['site-header'],
    text: 'My Site',
});

const page = IO.static('main', {}, [() => header, () => IO.static('p', { text: 'Static content for SEO' })]);

Interactive Islands

// Interactive island with hydration
const counterIsland = IO.island('div', {
    hydration: { 'client:visible': true }, // Lazy hydration
    fallback: () => IO.static('div', { text: 'Loading...' }),
    component: () => {
        const counter = new IO('div');
        const [count, setCount] = counter.state(0);

        counter.components = [
            () => new IO('span', { text: `Count: ${count()}` }),
            () =>
                new IO('button', {
                    text: '+',
                    events: { click: () => setCount(count() + 1) },
                }),
        ];

        return counter;
    },
});

// Hybrid page
const hybridPage = IO.static('main', {}, [
    () => IO.static('h1', { text: 'Static page' }),
    () => counterIsland(), // Interactive island
    () => IO.static('footer', { text: 'Static footer' }),
]);

Hydration Strategies

• client:load — immediate hydration
• client:idle — hydration when browser is idle
• client:visible — lazy hydration (on viewport)
• client:media — conditional hydration (media queries)

Data Bridge System

import { IslandDataBridge } from 'io-reactive';

// Set data between islands
IslandDataBridge.setData('user', { name: 'John', theme: 'dark' });

// Subscribe to changes
IslandDataBridge.subscribe('user', (userData) => {
    updateTheme(userData.theme);
});

📖 Detailed documentation on islands architecture

2. Directives

• model — two-way binding:

  <input :model="[() => state.value, v => state.value = v]" />

• validate — validation:

  <input :model="..." :validate="v => v.length > 2 || 'At least 3 characters'" />

• onSubmit — handle Enter:

  <input :model="..." :onSubmit="v => alert(v)" />

• debounce — update delay:

  <input :model="..." :debounce="300" />

• custom — your own directives:

  <input :custom="[{ name: 'my', init: (el, v) => ... }]" />

3. Reactivity

• Signals and state:

  const count = IO.signal(0);
  count.value++;

• Automatic effects:

  IO.effect(() => console.log(count.value));

4. Validation and Forms

• Built-in validators:

  import { required, minLength } from 'io-reactive/validators';
  <input :validate="required" />
  <input :validate="minLength(3)" />

• Input masks:

  <input :mask="{ pattern: '+1 (###) ###-####' }" />

5. Integration and Extensibility

• Compatible with any framework (can be used as standalone directives or islands)
• Extensible architecture: write your own directives, plugins, islands

Performance

Islands architecture provides:

• Minimal JavaScript bundle — only code for interactive islands is loaded
• Fast Time-to-Interactive — critical content is static
• Core Web Vitals optimization — lazy hydration does not block rendering
• SEO benefits — static HTML is fully indexed

Documentation and Examples

• Islands architecture — detailed guide on Islands
• Documentation and guides
• Demos and examples
• Plans and architecture

License

MIT

Публикация пакета и типы

Как опубликовать новую версию

1. Увеличьте версию:

   npm version patch --no-git-tag-version --workspace=packages/io-reactive

2. Соберите пакет:

   npm run build -w io-reactive

3. Проверьте, что в dist/ есть .js и .d.ts:

   ls packages/io-reactive/dist/

4. Опубликуйте:

   npm publish --access public --workspace=packages/io-reactive

Как работают типы

• Все типы автоматически подтягиваются через зависимость @oi-reactive/shared-types.
• Пользователю не нужно явно устанавливать shared-types — типы доступны "из коробки" после установки io-reactive.