[Docs] API

Here’s a draft for API docs.

atom

atom is a function to create an atom config. It’s an object and the object identity is important. You can create it from everywhere. Once created, you shouldn’t modify the object. (Note: There might be an advanced use case to mutate atom configs after creation. At the moment, it’s not officially supported though.)

const primitiveAtom = atom(initialValue)
const derivedAtomWithRead = atom(readFunction)
const derivedAtomWithReadWrite = atom(readFunction, writeFunction)
const derivedAtomWithWriteOnly = atom(null, writeFunction)

There are two kinds of atoms: a writable atom and a read-only atom Primitive atoms are always writable. Derived atoms are writable if writeFunction is specified. The writeFunction of primitive atoms is equivalent to the setState of React.useState.

The signature of readFunction is (get) => Value | Promise<Value>, and get is a function that takes an atom config and returns its value stored in Provider described below. Dependency is tracked, so if get is used for an atom at least once, then whenever the atom value is changed, the readFunction will be reevaluated.

The signature of writeFunction is (get, set, update) => void | Promise<void>. get is similar to the one described above, but it doesn’t track the dependency. set is a function that takes an atom config and a new value, and update the atom value in Provider. update is an arbitrary value that we receive from the updating function returned by useAtom described below.

Provider

Atom configs don’t hold values. Atom values are stored in a Provider. A Provider can be used like React context provider. Usually, we place one Provider at the root of the app, however you could use multiple Providers, each storing different atom values for its component tree.

const Root = () => (
  <Provider>
    <App />
  </Provider>
)

useAtom

The useAtom hook is to read an atom value stored in the Provider. It returns the atom value and an updating function as a tuple, just like useState. It takes an atom config created with atom(). Initially, there is no value stored in the Provider. At the first time the atom is used via useAtom, it will add an initial value in the Provider. If the atom is a derived atom, the read function is executed to compute an initial value. When an atom is no longer used, meaning the component using it is unmounted, the value is removed from the Provider.

const [value, updateValue] = useAtom(anAtom)

The updateValue takes just one argument, which will be passed to the third argument of writeFunction of the atom. The behavior is totally depends on how the writeFunction is implemented.

[dai-shi]

@gauravkumar37

  return [...useAtom(dataAtom), dataAtom] as const;

would also work.

[dai-shi]

@hsw107 You can define atoms anywhere in any files, export them, and import them where needed. If you are asking some best practices to organize atoms in files, it’s a good question. We’d like to collect various use cases and find a good pattern.