# Introduction

Valdres is a fast, reactive state management library for JavaScript and React. It's inspired by Recoil and Jotai with an emphasis on performance.

## Installation

npm
bun
yarn
pnpm

```bash
npm install valdres valdres-react
```

```bash
bun add valdres valdres-react
```

```bash
yarn add valdres valdres-react
```

```bash
pnpm add valdres valdres-react
```

## Quick Start

Create atoms to hold your state and selectors to derive computed values:

```ts
import { atom, selector } from "valdres"

const countAtom = atom(0)
const doubledSelector = selector(get => get(countAtom) * 2)
```

Use them in your React components:

```tsx
import { useAtom, useValue } from "valdres-react"

function Counter() {
    const [count, setCount] = useAtom(countAtom)
    const doubled = useValue(doubledSelector)

    return (
        <div>
            <p>Count: {count}</p>
            <p>Doubled: {doubled}</p>
            <button onClick={() => setCount(c => c + 1)}>+</button>
        </div>
    )
}
```

## Key Concepts

- **Atoms** hold pieces of state. They can be read and written from anywhere.
- **Selectors** derive computed state from atoms. They update automatically when dependencies change.
- **Families** (`atomFamily`, `selectorFamily`) create collections of atoms/selectors keyed by a parameter.
- **Stores** hold all atom values. A default global store is used unless you provide a `<Provider>`.

> **Tip**
>
>
> The core `valdres` package is framework-agnostic. You can use it with React via `valdres-react`, or without any framework at all.

## Quick Migrate

Already using Recoil or Jotai? Migration is a one-line import change:

```tsx
// From Recoil
import { atom, selector } from "@valdres-react/recoil"

// From Jotai
import { atom, createStore } from "@valdres-react/jotai"
```

> **Note**
>
>
> The compatibility packages mirror the original APIs, so most of your existing code works unchanged. See the [Jotai](https://valdres.dev/guides/vs-jotai) and [Recoil](https://valdres.dev/guides/vs-recoil) comparison guides for details.