migrating-to-v2-api.mdx

---
title: v2 API migration
description: New "Async" API
nav: 7.0
---

RFC: https://github.com/pmndrs/jotai/discussions/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.

## What are new features

### Vanilla library

Jotai comes with vanilla (non-React) functions
and React functions separately.
They are provided from alternate entry points like `jotai/vanilla`.

### Store API

Jotai exposes store interface so that you can directly manipulate atom values.

```js
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.

### More flexible atom `write` function

The write function can accept multiple arguments,
and return a value.

```js
atom(
  (get) => get(...),
  (get, set, arg1, arg2, ...) => {
    ...
    return someValue
  }
)
```

## What are breaking

### Async atoms are no longer special

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.

### Writable atom type is changed (TypeScript only)

```ts
// 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.

### Some functions are dropped

- Provider's `initialValues` prop is removed, because `store` is more flexible.
- Provider's scope props is removed, because you can create own context.
- `abortableAtom` util is removed, because the feature is included by default
- `waitForAll` util is removed, because `Promise.all` just works

## Migration guides

### Async atoms

`get` function for read function of async atoms
doesn't resolve promises, so you have to put `await` or `.then()`.

In short, the change is something like the following.
(If you are TypeScript users, types will tell where to changes.)

#### Previous API

```js
const asyncAtom = atom(async () => 'hello')
const derivedAtom = atom((get) => get(asyncAtom).toUppercase())
```

#### New API

```js
const asyncAtom = atom(async () => 'hello')
const derivedAtom = atom(async (get) => (await get(asyncAtom)).toUppercase())
// or
const derivedAtom = atom((get) => get(asyncAtom).then((x) => x.toUppercase()))
```

### Provider's `initialValues` prop

#### Previous API

```jsx
const countAtom = atom(0)

  // in component
  <Provider initialValues={[[countAtom, 1]]}>
    ...
```

#### New API

```jsx
const countAtom = atom(0)

const HydrateAtoms = ({ initialValues, children }) => {
  useHydrateAtoms(initialValues)
  return children
}

  // in component
  <Provider>
    <HydrateAtoms initialValues={[[countAtom, 1]]}>
      ...
```

### Provider's `scope` prop

#### Previous API

```jsx
const myScope = Symbol()

  // Parent component
  <Provider scope={myScope}>
    ...
  </Provider>

  // Child component
  useAtom(..., myScope)
```

#### New API

```jsx
const MyContext = createContext()
const store = createStore()

  // Parent component
  <MyContext.Provider value={store}>
    ...
  </MyContext.Provider>

  // Child Component
  const store = useContext(MyContext)
  useAtom(..., { store })
```

### `abortableAtom` util

You no longer need the previous `abortableAtom` util,
because it's now supported with the normal `atom`.

#### Previous API

```js
const asyncAtom = abortableAtom(async (get, { signal }) => {
 ...
}
```

#### New API

```js
const asyncAtom = atom(async (get, { signal }) => {
  ...
}
```

### `waitForAll` util

You no longer need the previous `waitForAll` util,
because we can use native Promise APIs.

#### Previous API

```js
const allAtom = waitForAll([fooAtom, barAtom])
```

#### New API

```js
const allAtom = atom((get) => Promise.all([get(fooAtom), get(barAtom)]))
```

## Some other changes

### Utils

- `atomWithStorage` util's `delayInit` is removed as being default.
- `useHydrateAtoms` can only accept writable atoms.

### Import statements

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`

```js
// 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'
```