fluidstate-mobx/README.md

MobX-based reactive layer for fluidstate

# fluidstate-mobx

[**View interactive documentation on the official website.**](https://fluidstate.gitlab.io/layers_mobx.html)

`fluidstate-mobx` is the MobX-based reactive layer for [`fluidstate`](https://gitlab.com/fluidstate/fluidstate). It bridges the declarative, ergonomic API of `fluidstate` with the powerful and battle-tested reactive engine of [MobX](https://mobx.js.org/).

## Key Features

- **Seamless Integration:** Implements the `fluidstate`'s `ReactiveLayer`, providing atoms, computed values, and reactions powered by MobX's core APIs (`createAtom`, `computed`, `autorun`).

- **State Isolation:** Automatically configures MobX with `isolateGlobalState: true` to ensure it can coexist with other MobX instances in the same application without conflicts.

- **Enables `fluidstate`:** Once configured, you can use the complete feature set of `fluidstate` for your state management needs.

- **Convenient MobX Access:** Re-exports all MobX APIs, allowing you to use them directly without adding `mobx` as a separate dependency.

## Installation

To use `fluidstate` with MobX, you need to install `fluidstate` and `fluidstate-mobx`:

```bash
npm install fluidstate fluidstate-mobx
```

or

```bash
yarn add fluidstate fluidstate-mobx
```

## Usage

To enable `fluidstate`, you must provide it with the MobX reactive layer. This is a one-time setup at your application's entry point.

```typescript
import {
	provideReactiveLayer,
	createReactive,
	createReaction,
	runAction,
} from "fluidstate";
import { getReactiveLayer } from "fluidstate-mobx";

// 1. Get the reactive layer from fluidstate-mobx
const reactiveLayer = getReactiveLayer();

// 2. Provide it to fluidstate
provideReactiveLayer(reactiveLayer);

// 3. You can now use the fluidstate API throughout your application
const counter = createReactive({ value: 0 });

createReaction(() => {
	console.log(`Counter value: ${counter.value}`);
});
// LOGS: Counter value: 0

runAction(() => {
	counter.value++;
});
// LOGS: Counter value: 1
```

After this setup, you can use the `fluidstate` package for all your state management tasks. For more details on `createReactive`, `createReaction`, and other features, please refer to the [main `fluidstate` documentation](https://gitlab.com/fluidstate/fluidstate).

## Using MobX APIs

While `fluidstate` provides a high-level abstraction, you may occasionally need to use MobX APIs directly. For convenience, `fluidstate-mobx` re-exports the entire MobX library from a separate entry point.

This ensures you are using the same instance of MobX that powers `fluidstate`, which can help prevent version conflicts or bundling issues.

```typescript
// Instead of a direct import: import { observable } from "mobx";
import { observable } from "fluidstate-mobx/mobx";
```

This is an optional convenience and is not required for standard `fluidstate` usage.