React Getting Started

Installation

pnpm

pnpm add @blac/core @blac/react

npm

npm install @blac/core @blac/react

Requires React 18+ and TypeScript is recommended.

Basic usage

Define a Cubit for your state, then connect it to a component with useBloc:

import { Cubit } from '@blac/core';
import { useBloc } from '@blac/react';

class CounterCubit extends Cubit<{ count: number }> {
  constructor() {
    super({ count: 0 });
  }

  increment = () => this.emit({ count: this.state.count + 1 });
  decrement = () => this.update((s) => ({ count: s.count - 1 }));
}

function Counter() {
  const [state, counter] = useBloc(CounterCubit);

  return (
    <div>
      <p>Count: {state.count}</p>
      <button onClick={counter.increment}>+</button>
      <button onClick={counter.decrement}>-</button>
    </div>
  );
}

useBloc returns [state, bloc]:

• state — current state, tracked for re-renders (only properties you read trigger updates)
• bloc — the Cubit instance (call methods on it)

Global configuration

Optionally configure defaults for all useBloc calls:

import { configureBlacReact } from '@blac/react';

configureBlacReact({
  autoTrack: true, // default: true
});

Tracking modes at a glance

Mode	How to enable	Re-renders when
Auto-tracking	Default	Tracked properties change
Manual deps	dependencies: (s) => [s.count]	Dependency values change
No tracking	autoTrack: false	Any state change

See Dependency Tracking for details.

Instance modes at a glance

Mode	How to enable	Behavior
Shared	Default	All components share one instance
Isolated	@blac({ isolated: true })	Each useBloc call gets a new instance
Named	{ instanceId: 'key' }	Shared within same key

See Shared vs Isolated for details.

What's next?

• useBloc — Full hook reference
• Dependency Tracking — Understanding re-render optimization
• Performance — Patterns and anti-patterns