Ripple-Reactive

Quick Start & Installation

Get up and running with Ripple.js and learn the core concepts in under 5 minutes.

Installation

Ripple.js is available on npm and works seamlessly in any JavaScript or TypeScript environment.

Install the core package

npm install ripple-reactive

(Optional) Install a framework adapter

If you are using React, Vue, or Svelte, install the framework alongside the core library.

npm install ripple-reactive react

Core Concepts

Ripple.js has three building blocks: Signals (state), Computed (derived values), and Effects (side effects). Here's how they work together:

import { signal, computed, effect } from 'ripple-reactive';

// 1. Signal — holds reactive state
const price = signal(29.99);
const quantity = signal(2);

// 2. Computed — derives a value (lazy + memoized)
const total = computed(() => price.value * quantity.value);
const withTax = computed(() => total.value * 1.18); // 18% GST

// 3. Effect — reacts to changes automatically
effect(() => {
  console.log(`Total: ₹${total.value.toFixed(2)}, With Tax: ₹${withTax.value.toFixed(2)}`);
});
// → "Total: ₹59.98, With Tax: ₹70.78"

quantity.value = 5;
// → "Total: ₹149.95, With Tax: ₹176.94"  ✨ automatic!

That's it — three primitives. Signals hold values, computed derives from them lazily, and effects react to changes. Everything else in Ripple.js builds on top of these.

Framework Integration

Ripple.js can be dropped into any major UI framework. Here is how to use the official adapters to bind signals directly to your components.

import { signal } from 'ripple-reactive';
import { useSignalValue } from 'ripple-reactive/react';

// Define state outside the component
const count = signal(0);

export function Counter() {
  // Bind the signal to the React component lifecycle
  const value = useSignalValue(count);
  
  return (
    <button onClick={() => count.value++}>
      Count: {value}
    </button>
  );
}

Performance Note

Ripple.js utilizes a push-pull hybrid engine. Mutations push dirty flags instantly, but computed values are lazy and only evaluate when read. This guarantees glitch-free propagation with zero intermediate stale states.

On this page