fluidstate-alien/README.md

Alien Signals-based reactive layer for fluidstate

# fluidstate-alien

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

`fluidstate-alien` is the [Alien Signals](https://github.com/stackblitz/alien-signals)-based reactive layer for [`fluidstate`](https://gitlab.com/fluidstate/fluidstate). It bridges the declarative, ergonomic API of `fluidstate` with one of the fastest and most efficient implementations of the reactivity system.

## Key Features

- **Seamless Integration:** Implements the `fluidstate`'s `ReactiveLayer`, providing atoms, computed values, and reactions powered by Alien Signal's core APIs.

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

- **Convenient Alien Signals Access:** Re-exports all Alien Signals APIs used by `fluidstate-alien`, allowing you to use them directly without adding `alien-signals` as a separate dependency.

## Installation

To use `fluidstate` with Alien Signals, you need to install `fluidstate` and `fluidstate-alien`:

```bash
npm install fluidstate fluidstate-alien
```

or

```bash
yarn add fluidstate fluidstate-alien
```

## Usage

To enable `fluidstate`, you must provide it with the Alien Signals 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-alien";

// 1. Get the reactive layer from fluidstate-alien
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 Alien Signals APIs

While `fluidstate` provides a high-level abstraction, you may occasionally need to use Alien Signals APIs directly. For convenience, `fluidstate-alien` re-exports the subset of Alien Signals library used by `fluidstate-alien` from a separate entry point.

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

```typescript
// Instead of a direct import: import { computed } from "alien-signals";
import { computed } from "fluidstate-alien/alien-signals";
```

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