Migration Guide

Valdres provides drop-in compatibility packages for both Recoil and Jotai. You can migrate your entire app by changing a single import — then gradually adopt the native Valdres API at your own pace.

From Recoil

Replace your Recoil import with the Valdres compatibility layer:

// Before
import { atom, selector, useRecoilState } from "recoil"

// After
import { atom, selector, useRecoilState } from "@valdres-react/recoil"

Install the package:

npm install @valdres-react/recoil

That's it. Most existing Recoil code keeps working — now backed by Valdres under the hood — so you can migrate the import first and adopt the native API at your own pace.

From Jotai

Replace your Jotai import with the Valdres compatibility layer:

// Before
import { atom, createStore } from "jotai"

// After
import { atom, createStore } from "@valdres-react/jotai"

Install the package:

npm install @valdres-react/jotai

Gradual adoption

Once you've migrated, you can incrementally adopt the native Valdres API:

1. Replace imports — Switch from @valdres-react/recoil or @valdres-react/jotai to valdres and valdres-react
2. Use native hooks — Replace useRecoilState with useAtom, useRecoilValue with useValue
3. Adopt new features — Start using transactions, first-class families, and framework-agnostic state

// Compatibility layer
import { atom } from "@valdres-react/recoil"
import { useRecoilState } from "@valdres-react/recoil"

// Native Valdres
import { atom } from "valdres"
import { useAtom } from "valdres-react"

Key differences from Recoil

Key differences from Jotai