Recoil Persist

Tiny module for recoil to store and sync state to Storage. It is only 354 bytes (minified and gzipped). No dependencies. Size Limit controls the size.

Demo

If you are using recoil-persist with version 1.x.x please check migration guide to version 2.x.x.

1import React from 'react'
2import ReactDOM from 'react-dom'
3import App from './App'
4import { atom, RecoilRoot, useRecoilState } from 'recoil'
5import { recoilPersist } from 'recoil-persist'
6
7const { persistAtom } = recoilPersist()
8
9const counterState = atom({
10  key: 'count',
11  default: 0,
12  effects_UNSTABLE: [persistAtom],
13})
14
15function App() {
16  const [count, setCount] = useRecoilState(counterState)
17  return (
18    <div>
19      <h3>Counter: {count}</h3>
20      <button onClick={() => setCount(count + 1)}>Increase</button>
21      <button onClick={() => setCount(count - 1)}>Decrease</button>
22    </div>
23  )
24}
25
26ReactDOM.render(
27  <React.StrictMode>
28    <RecoilRoot>
29      <App />
30    </RecoilRoot>
31  </React.StrictMode>,
32  document.getElementById('root'),
33)

Install

npm install recoil-persist

or

yarn add recoil-persist

Now you could add persisting a state to your app:

1import React from 'react';
2import ReactDOM from 'react-dom';
3import App from './App';
4import { RecoilRoot } from "recoil";
5+import { recoilPersist } from 'recoil-persist'
6
7+const { persistAtom } = recoilPersist()
8
9const counterState = atom({
10  key: 'count',
11  default: 0,
12+ effects_UNSTABLE: [persistAtom],
13})
14
15function App() {
16  const [count, setCount] = useRecoilState(counterState)
17  return (
18    <div>
19      <h3>Counter: {count}</h3>
20      <button onClick={() => setCount(count + 1)}>Increase</button>
21      <button onClick={() => setCount(count - 1)}>Decrease</button>
22    </div>
23  )
24}
25
26ReactDOM.render(
27  <React.StrictMode>
28    <RecoilRoot>
29      <App />
30    </RecoilRoot>
31  </React.StrictMode>,
32  document.getElementById('root'),
33)

After this each changes in atom will be store and sync to localStorage.

Usage

1import { recoilPersist } from 'recoil-persist'
2
3const { persistAtom } = recoilPersist({
4  key: 'recoil-persist', // this key is using to store data in local storage
5  storage: localStorage, // configure which storage will be used to store the data
6  converter: JSON // configure how values will be serialized/deserialized in storage
7})

Server Side Rendering

If you are using SSR you could see that error:

Unhandled Runtime Error

Error: Text content does not match server-rendered HTML.

It happens because on server you don't have any storages and react renders component with default value. However in browser it is rendering with values from storage. To prevent it we need to introduce hook for render with default value for the first time.

1const defaultValue = [{ id: 1 }]
2
3export const recoilTest = atom<{ id: number }[]>({
4  key: "recoilTest",
5  default: defaultValue,
6  effects_UNSTABLE: [persistAtom],
7});
8
9export function useSSR() {
10  const [isInitial, setIsInitial] = useState(true);
11  const [value, setValue] = useRecoilState(recoilTest);
12
13  useEffect(() => {
14    setIsInitial(false);
15  }, []);
16
17  return [isInitial ? defaultValue : value, setValue] as const;
18}
19
20
21export default function Component() {
22  const [text, setText] = useSSR();
23
24  // rest of the code
25}

API

recoilPersist(config)

config parameter

1type config.key = String

Default value of config.key is recoil-persist. This key is using to store data in storage.

1type config.storage = Storage

Set config.storage with sessionStorage or other Storage implementation to change storage target. Otherwise localStorage is used (default).

1type config.converter = {
2  stringify: (value: any) => string
3  parse: (value: string) => any
4}

Set config.converter to an object which implements both stringify and parse functions to convert state values to and from strings. One use of this would be to wrap the standard JSON.stringify and JSON.parse functions, e.g. to insert your own reviver and replacer functions:

1{
2  parse: (value) => JSON.parse(value, myCustomReviver),
3  stringify: (value) =>  JSON.stringify(value, myCustomReplacer)
4};

Migration from version 1.x.x to 2.x.x

The API changed from version 1.x.x.

To update your code just use this migration guide:

1import React from 'react';
2import ReactDOM from 'react-dom';
3import App from './App';
4import { RecoilRoot } from "recoil";
5import { recoilPersist } from 'recoil-persist' // import stay the same
6
7const {
8-  RecoilPersist,
9-  updateState
10+  persistAtom
11} = recoilPersist(
12-   ['count'], // no need for specifying atoms keys
13    {
14        key: 'recoil-persist', // configuration stay the same too
15        storage: localStorage
16    }
17)
18
19const counterState = atom({
20  key: 'count',
21  default: 0,
22- persistence_UNSTABLE: { // Please remove persistence_UNSTABLE from atom definition
23-   type: 'log',
24- },
25+ effects_UNSTABLE: [persistAtom], // Please add effects_UNSTABLE key to atom definition
26})
27
28function App() {
29  const [count, setCount] = useRecoilState(counterState)
30  return (
31    <div>
32      <h3>Counter: {count}</h3>
33      <button onClick={() => setCount(count + 1)}>Increase</button>
34      <button onClick={() => setCount(count - 1)}>Decrease</button>
35    </div>
36  )
37}
38
39ReactDOM.render(
40  <React.StrictMode>
41-   <RecoilRoot initializeState={({set}) => updateState({set})>
42+   <RecoilRoot> // Please remove updateState function from initiallizeState
43-     <RecoilPersist /> // and also remove RecoilPersist component
44      <App />
45    </RecoilRoot>
46  </React.StrictMode>,
47  document.getElementById('root')
48);

Demo

$ git clone git@github.com:polemius/recoil-persist.git
$ cd recoil-persist
$ npm install
$ npm run start

Please open localhost:1234.