Roadmap to v1

[dai-shi]

We are getting ready. Here's action items.

Fixing bugs

For this we need more bug reports.

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

Improving docs

This is most important for v1.

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

Improving types and tests

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

Improving apis

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

Benchmarking

• js-framework-benchmark @Thisen
• Performance measurement / Benchmark tool #245 Performance measurement Benchmark tool #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.

• Snaphot-based devtools #388 Snapshot-based devtools @Thisen

Adding features

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

• jotai/valtio feat: jotai/valtio #405
• jotai/zustand feat: jotai/zustand #419
• jotai/redux feat: jotai/redux #421
• jotai/rxjs feat: jotai/rxjs #341
• Create a bindings to the URQL GraphQL Client. #427 Create a bindings to the URQL GraphQL Client. feat: jotai/urql #463 @dai-shi
• [jotai/query] atomWithMutation #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.

[Thisen]

I think basic devtools should be a part of v1. Then we will know that the snapshot parts are stable.

[Aslemammad]

@Aslemammad, I think I'm gonna do some about blog posts. But I have to finish some stuff going on here.

[RIP21]

If some will wrap urql client into jotai it will be awesome :) But I guess it will require some good knowledge of internals to make it right.
This thingy :)
https://github.com/FormidableLabs/urql

[dai-shi]

@RIP21 Nice idea. Would you create a dedicated issue please? I'm interested, but if someone is too, they can try.

[RIP21]

@dai-shi done #427 :)
BTW, thanks for your work! :) Love Jotai so far :)

[dai-shi]

We did it! 🎉 🎉 🎉