feat(util): atomWithStorage

[sandren]

There are examples of how to add persistence to individual atoms in the docs, but I would like to create a robust atomWithStorage utility that covers most use cases, including localStorage or sessionStorage for React as well as AsyncStorage for React Native. Also note that the stored value is intentionally populated in the onMount method rather than the base atom() initialization to support atomWithStorage usage in SSR contexts such as Next.js and Gatsby. The first commit is a work in progress.

Progress

• impl
• tests
• docs -> a separate pr https://github.com/pmndrs/website/pull/77

[dai-shi]

Thanks for opening this up! I expect this is going to be a good one and thus taking time. Please bare with me. No ETA.

[dai-shi]

Do we accept function update? If so, L24-L26 should be implemented so. There's no magic.

[sandren]

Can you elaborate?

[dai-shi]

It has to be:

    (get, set, update: Update) => {
      const newValue = typeof update === 'function' ? update(get(baseAtom)) : update
      set(baseAtom, newValue)
      window.localStorage.setItem(key, JSON.stringify(newValue))
    }

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit 77e45b6:

Sandbox	Source
React	Configuration
React Typescript	Configuration

[dai-shi]

The WIP version looks actually good, and is worth a guide in docs.

To make if a flexible util, we want to abstract the storage api.

type Storage<Value> = {
  getItem: (key: string) => Value | Promise<Value>
  setItem: (key: string, newValue: Value) => void | Promise<void>
}

export function atomWithStorage<Value>(key: string, default: Value, getStorage?: () => Storage<Value>): PrimitiveAtom<Value>

[vercel]

This pull request is being automatically deployed with Vercel (learn more).
To see the status of your deployment, click below or on the icon next to each commit.

🔍 Inspect: https://vercel.com/pmndrs/jotai/GqoydTYPnoGaaqDbFqTbv4X9sDWt
✅ Preview: https://jotai-git-fork-sandren-feat-atom-with-storage-pmndrs.vercel.app

[Aslemammad]

@sandren Wow, I really loved this idea, Hope it gets released soon so I can use it in my new project.

[ghmeec]

this is awesome, i haven't been able to test in RN environment, would there be a problem since getItem and setItem methods are async?

[dai-shi]

@ghmeec We hoped this would support AsyncStorage, but not thoroughly tested. Would you give it a try?

[jrobber]

@dai-shi Awesome work here!

I can confirm that atomWithStorage works on react-native if your atom is a string. It does appear to any JSON.stringify or JSON.parse.

To get other types I had to dig through Jotai code until I found createJSONStorage.
I was then able to get other types working like this.

export const userAtom = atomWithStorage<User | null>('USER', null, createJSONStorage(()=> AsyncStorage));

For me, this is acceptable. I recommend maybe just adding it to the docs.

[dai-shi]

Yeah, we don't have enough docs about atomWithStorage...

[thinkdj]

Often, we need to store sensitive data like a token or basic authentication info for persistence, and storing such data plainly to localStorage seems less secure. Provision for a custom hook for encrypt/decrypt would be great to see

[dai-shi]

You should be able to customize storage.

[thinkdj]

You should be able to customize storage.

Ah! Missed this. Thank you.

Reference for others: Customizing storage: Docs & sample.