title | description | nav |
---|---|---|
Migrating to Jotai v2 API |
New "Async" API |
3.13 |
RFC: #1514
Jotai v1 is released at June 2022, and there has been various feedbacks. React also proposes first-class support for promises. Jotai v2 will have a new API.
Unfortunately, there are some breaking changes along with new features.
Jotai comes with vanilla (non-React) functions
and React functions separately.
They are provided from alternate entry points like jotai/vanilla
.
Jotai exposes store interface so that you can directly manipulate atom values.
import { createStore } from 'jotai' // or from 'jotai/vanilla'
const store = createStore()
store.set(fooAtom, 'foo')
console.log(store.get(fooAtom)) // prints "foo"
const unsub = store.sub(fooAtom, () => {
console.log('fooAtom value in store is changed')
})
// call unsub() to unsubscribe.
You can also create your own React Context to pass a store.
The write function can accept multiple arguments, and return a value.
atom(
(get) => get(...),
(get, set, arg1, arg2, ...) => {
...
return someValue
}
)
Async atoms are just normal atoms with promise values.
Atoms getter functions don't resolve promises.
On the other hand, useAtom
hook continues to resolve promises.
// Old
WritableAtom<Value, Arg, Result extends void | Promise<void>>
// New
WritableAtom<Value, Args extends unknown[], Result>
In general, we should avoid using WritableAtom
type directly.
- Provider's
initialValues
prop is removed, becausestore
is more flexible. - Provider's scope props is removed, because you can create own context.
abortableAtom
util is removed, becuase the feature is included by defaultwaitForAll
util is removed, becausePromise.all
just works
get
function for read function of async atoms
doesn't resolve promises, so you have to put await
.
In short, the change is something like the following. (If you are TypeScript users, types will tell where to changes.)
const asyncAtom = atom(async () => 'hello')
const derivedAtom = atom((get) => get(asyncAtom).toUppercase())
const asyncAtom = atom(async () => 'hello')
const derivedAtom = atom(async (get) => (await get(asyncAtom)).toUppercase())
const countAtom = atom(0)
<Provider initialValues={[[countAtom, 1]]}>
...
</Provider>
const countAtom = atom(0)
const store = createStore()
store.set(countAtom, 1)
<Provider store={store}>
...
</Provider>
const myScope = Symbol()
// Parent component
<Provider scope={myScope}>
...
</Provider>
// Child component
useAtom(..., myScope)
const MyContext = createContext()
const store = createStore()
// Parent component
<MyContext.Provider value={store}>
...
</MyContext.Provider>
// Child Component
const store = useContext(MyContext)
useAtom(..., { store })
You no longer need the previous abortableAtom
util,
because it's now supported with the normal atom
.
const asyncAtom = abortableAtom(async (get, { signal }) => {
...
}
const asyncAtom = atom(async (get, { signal }) => {
...
}
You no longer need the previous waitForAll
util,
because we can use native Promise APIs.
const allAtom = waitForAll([fooAtom, barAtom])
const allAtom = atom((get) => Promise.all([get(fooAtom), get(barAtom)]))
atomWithStorage
util'sdelayInit
is removed as being default.useHydrateAtoms
can only accept writable atoms.
The v2 API is also provided from alternate entry points for library authors and non-React users.
jotai/vanilla
jotai/vanilla/utils
jotai/react
jotai/react/utils
// Available since v1.11.0
import { atom } from 'jotai/vanilla'
import { useAtom } from 'jotai/react'
// Available since v2.0.0
import { atom } from 'jotai' // is same as 'jotai/vanilla'
import { useAtom } from 'jotai' // is same as 'jotai/react'