Quick Start

Beta / pre-release

BlaC v2 is in pre-release (beta). While in beta, breaking API changes may ship in patch releases without a major version bump — pin exact versions and check the changelog before upgrading. Strict semver resumes once v2 is officially out of beta.

Installation

pnpm

pnpm add @blac/core @blac/react

npm

npm install @blac/core @blac/react

yarn

yarn add @blac/core @blac/react

BlaC requires React 18+ and TypeScript is strongly recommended.

Recommended tsconfig.json

BlaC works with a standard strict React setup. The @blac() decorator (used for keepAlive, static key, and other options) works as either a legacy (experimentalDecorators) or a TC39/stage-3 decorator — enable decorator support in your tsconfig to use the @blac(...) syntax. Or skip decorators entirely with the functional form — blac({ ... })(class extends Cubit { ... }) — which needs no extra compiler flags.

{
  "compilerOptions": {
    "target": "ESNext",
    "jsx": "react-jsx",
    "strict": true,
    "useDefineForClassFields": true,
    "experimentalDecorators": true, // only if you use @blac(...) decorator syntax
  },
}

Step 1: Define a Cubit

A Cubit is a class that holds state and exposes methods to change it.

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

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 }));
  reset = () => this.patch({ count: 0 });
}

Three ways to change state:

Method	What it does	When to use
emit(newState)	Replace the entire state	You have the full new state ready
update(fn)	Derive new state from current	You need to read current state first
patch(partial)	Deep-merge partial changes (DeepPartial<S>)	You want to update some fields and keep the rest

emit and update replace; only patch merges

emit(next) and update(fn) set state to exactly what you return — any key you forget to include is dropped. patch(partial) deep-merges, so the keys you omit survive. The increment above is fine because count is the only key; for multi-field state, either spread the previous state (update((s) => ({ ...s, count: s.count + 1 }))) or use patch.

Define methods as arrow-function fields

Every method here is an arrow-function class field (increment = () => …), not a regular method. This binds this to the instance, so counter.increment keeps working when passed straight to onClick. A regular method (increment() { … }) loses this once detached from the instance.

Step 2: Use it in React

The useBloc hook connects your component to a Cubit.

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

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

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

useBloc returns a tuple:

• state — the current state snapshot (tracked for re-renders)
• counter — the Cubit instance (call methods on it)

Step 3: Share state across components

By default, every component that calls useBloc(CounterCubit) gets the same instance. State is automatically shared.

function CounterDisplay() {
  const [state] = useBloc(CounterCubit);
  return <p>Count: {state.count}</p>;
}

function CounterControls() {
  const [, counter] = useBloc(CounterCubit);
  return <button onClick={counter.increment}>+</button>;
}

function App() {
  return (
    <>
      <CounterDisplay />
      <CounterControls />
    </>
  );
}

When CounterControls calls increment, CounterDisplay re-renders with the new count. No providers, no context, no prop drilling.

Step 4: Add business logic

Keep logic in the class, not in the component.

class TodoCubit extends Cubit<{ items: string[]; input: string }> {
  constructor() {
    super({ items: [], input: '' });
  }

  setInput = (value: string) => this.patch({ input: value });

  addTodo = () => {
    const trimmed = this.state.input.trim();
    if (!trimmed) return;
    // emit/update REPLACE state, so list every key you want to keep.
    this.update((s) => ({ items: [...s.items, trimmed], input: '' }));
  };

  removeTodo = (index: number) => {
    // patch deep-merges, so we only mention the key we change.
    this.patch({ items: this.state.items.filter((_, i) => i !== index) });
  };

  get isEmpty() {
    return this.state.items.length === 0;
  }
}

Notice the two write styles: addTodo uses update and lists both keys (replacing the whole state), while removeTodo uses patch and mentions only items (merging into the rest). Both are correct — the difference is exactly the replace-vs-merge rule from Step 1.

Getters like isEmpty derive a value on every read, so they can never drift from items. When a component reads todo.isEmpty during render, auto-tracking records the getter’s underlying this.state.items.length read through the proxy. Use select only when you want the getter’s return value to be the explicit re-render boundary. The full rule is in Dependency Tracking. For async work (loading flags, fetches, request guards), see Patterns & Recipes.

Component not re-rendering?

The two most common first-time causes:

1. Reading raw state off the bloc instead of the state proxy. Auto-tracking records reads on the destructured state value and on getters read from the returned bloc proxy during render. It does not track counter.state.count, because that reads raw state directly. Read through state in render, or expose a getter that reads this.state.
2. Expecting emit/update to merge. They replace the whole state, so any key you omit is dropped. Use patch to merge, or spread the previous state.

The full symptom list is in Troubleshooting & FAQ.

Step 5: Fetch something

An async action is just a method that awaits and emits as it goes. Model the lifecycle as a status union so the view can render loading and error states, and use a request-id guard so a slow response can never overwrite a newer one.

type UserState =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; user: User }
  | { status: 'error'; message: string };

class UserCubit extends Cubit<UserState> {
  private requestId = 0;

  constructor() {
    super({ status: 'idle' });
  }

  load = async (id: string) => {
    const reqId = ++this.requestId; // claim the latest slot
    this.emit({ status: 'loading' });
    try {
      const user = await api.fetchUser(id);
      if (reqId !== this.requestId) return; // a newer call won; bail
      this.emit({ status: 'success', user });
    } catch (e) {
      if (reqId !== this.requestId) return;
      this.emit({ status: 'error', message: String(e) });
    }
  };
}

The view switches on state.status and TypeScript narrows each branch. Derived loading flags, the loadable surface, cancellation with AbortController, and why BlaC does not use React Suspense are all in the Async guide.

What just happened?

When you call useBloc(CounterCubit):

1. The registry checks if an instance of CounterCubit already exists
2. If not, it creates one and stores it. If yes, it returns the existing one
3. A ref count is incremented (tracking how many components use this instance)
4. The hook subscribes to state changes using auto-tracking — a Proxy wraps the state and records which properties your render function accesses
5. On re-render, only changes to those specific properties trigger an update
6. When the component unmounts, the ref count decrements. At zero, the instance is disposed

Each of these steps has a “why” worth understanding once your app grows — why a proxy beats selectors, why disposal is automatic, why updates batch on a microtask. That deep version lives in the Mental Model.

What’s next?

• Core Concepts — A quick tour of registry, tracking, and lifecycle
• Mental Model — The deep version of “what just happened?”
• Patterns & Recipes — Async patterns, cross-bloc communication, persistence
• Cubit — Full Cubit API
• useBloc — Hook options and tracking modes

See also

• Core Concepts — the quick conceptual tour
• Cubit — emit / update / patch in full
• useBloc — every hook option and both tracking modes
• DevTools — inspect state and re-renders in real time