Roadmap to v1

We are getting ready. Here’s action items.

Fixing bugs

For this we need more bug reports.

• #327 Snowpack atomState.d is not defined
• #351 Freezes when updating multiple async atoms
• #354 ‘The path “.” is not exported by “jotai”’ using esbuild
• #355 setAtom doesn’t bail on same value if component reads from another atom
• #373 “Too many re-renders.”
• #375 value from atom is not update and component is not rendered
• #389 Write function with delayed call to set
• #398 useAtomCallback doesn’t have types for 3-param signature
• #434 async read atoms keep waiting the first promise to be resolved and can’t be overriden by the second promise @dai-shi
• (#433) Improve atom() typing #438
• #442 Resolution of Promise atoms does not propagate correctly. @dai-shi
• #443 Endless API call with 0.16.2, strange behavior @dai-shi @Aslemammad
• #476 Bad setState() call when use atomWithQuery
• #490 [BUG] derived atoms don’t update depended on other atoms which update when router back
• #491 [useAtomCallback] Incorrect return type
• #492 [BUG] TypeError: source[GET_VERSION] is not a function
• (#500) atomWithQuery with enabled option doesn’t work on remount @dai-shi @Aslemammad
• #512 atomFamily not updating with param from another atom
• #517 [Bug] atom state not found in flush undefined (introduced in 0.16.11) #518

Improving docs

This is most important for v1.

• #335 [Docs] add provider-less mode
• #319 Docs: Intro with conceptual differences with Redux, Context API, etc.
• #401 [Docs] Improve Getting Started
• #402 [Docs] Improve introduction to async
• #429 [Docs] Rewrite persistence guide @dai-shi
• #435 [Docs] How to deal with atoms in atom guide @dai-shi
• #255 [Question] Best practices for large objects?
• #269 [Question] Can jotai be used without Suspense?
• #436 [Docs] Improve atomFamily typings to be obvious to use
• #252 [Question] How do you unit test Jotai atoms?
• demo website @sandren #519

Improving types and tests

• fix: export some types and hide some internal types #488
• #337 Add TS Except tests for v1 @Thisen

Improving apis

• feat(util): atomWithDefault #379
• Feature: waitFor utilities #358
• #385 Generalize atomFamily (BREAKING CHANGE)
• feat(util): atomWithStorage #394 @sandren
• feat(util): atomWithHash #407 @dai-shi
• #430 Support primitive atoms with a Promise as the initial value. @dai-shi
• feat(utils): add freezeAtomCreator, drop atomFrozenInDev (BREAKING CHANGE) #441 @dai-shi
• #231 Focus Atoms with async atoms?
• #452 extend atomWithImmer to accept normal update

Benchmarking

• js-framework-benchmark @Thisen
• #245 Performance measurement #486 @dai-shi
• Benchmark tool: porting react-redux-benchmarks @Aslemammad https://github.com/Aslemammad/react-state-benchmarks

Devtools

We have useDebugState in Provider and jotai/devtools for Redux DevTools Ext.

It would be nice to have a dedicated devtools.

• #388 Snapshot-based devtools @Thisen

Adding features

This is actually not required for v1, but nice to have.

• jotai/valtio #405
• jotai/zustand #419
• jotai/redux #421
• jotai/rxjs #341
• #427 Create a bindings to the URQL GraphQL Client. #463 @dai-shi
• #309 [jotai/query] atomWithMutation @aulneau
• [jotai/xstate] atomWithService, atomWithActor (maybe after v1)
• useAtomCallback for async @Thisen (from ideating)

Tutorials

Maybe we should do this outside repo. Anyone would like to write blog posts or something?

Release Note

• Prepare release note draft

Draft

Announcing Jotai v1

We are pleased to announce jotai v1 release! Jotai is a primitive and flexible state management library for React.

Demos:

• Text Length example
• Hacker News example
• Todos example

Global state like useState

Jotai’s atoms can be used like useState, but it’s global state.

const yearAtom = atom(2021)

const Component = () => {
  const [year, setYear] = useAtom(yearAtom)
  return <>{year} <button onClick={() => setYear((c) => c + 1)}>Next</button>
}

Derived state

You can create a derived atom with read function.

const meterAtom = atom(1000)
const kilometerAtom = atom((get) => get(meterAtom) / 1000)

Minimal API and additional utilities

Jotai core jotai exposes only two functions atom, useAtom and one optional component Provider.

We have more functions in separate bundles jotai/*, such as jotai/utils and jotai/devtools. For example, those include atomWithStorage, atomWithReset, atomFamily, to name a few. They are all implemented with the public api of jotai core. So, you can also create a similar third-party library.

Async support

Jotai comes with Suspense support. If your read function is async, it will suspend behind the scenes, and you wouldn’t need to care async state in your code.

const idAtom = atom('id001')
const dataAtom = atom(async (get) => {
  const response = await fetch(`.../${id}`)
  return response.json()
}

const Component = () => {
  const [data] = useAtom(dataAtom)
  return <>{data.title} - {data.author}</>
}

Notes about Suspense

We use the undocumented behavior of “Suspense for Lazy Loading” for any async. “Suspense for Data Fetching” is still to be finalized. Hence, this feature is technically unstable. We try our best to keep the API when it migrates.

Integrations

Jotai comes with various integrations. Some of them are complete, some are preliminary.

• jotai/immer: immer integration
• jotai/optics: optics-ts integration
• jotai/query: react-query integration
• jotai/xstate: xstate integration
• jotai/valtio: valtio integration
• jotai/zustand: zustand integration
• jotai/redux: redux integration

Moving forward

The core API should be stable for React 16.8 and above. All major issues are resolved, and if there is a bug by chance, we will fix it as soon as possible.

We will be adding more utility functions on top of core, and your use cases would be important. Free free to open a new discussion.

We are already working on new integrations for urql and rxjs. We have a plan to work on dedicated integration for nextjs.

When React releases a new version with Suspense and Concurrent support, we will start working on the next major version. Our hope is to keep the API compatible.

Notes about Versioning

We follow semantic versioning for core jotai. Note that type-only changes and sub bundles jotai/* don’t strictly follow the semver. Please check release notes for details.

[dai-shi]

We did it! 🎉 🎉 🎉

[RIP21]

@dai-shi done https://github.com/pmndrs/jotai/issues/427 😃 BTW, thanks for your work! 😃 Love Jotai so far 😃