Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/polemius/recoil-persist
Package for recoil state manager to persist and rehydrate store
https://github.com/polemius/recoil-persist
atoms localstorage recoil recoiljs sessionstorage storage
Last synced: 7 days ago
JSON representation
Package for recoil state manager to persist and rehydrate store
- Host: GitHub
- URL: https://github.com/polemius/recoil-persist
- Owner: polemius
- License: mit
- Created: 2020-05-19T05:40:32.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2023-12-22T04:07:26.000Z (about 1 year ago)
- Last Synced: 2024-05-12T10:02:09.101Z (9 months ago)
- Topics: atoms, localstorage, recoil, recoiljs, sessionstorage, storage
- Language: TypeScript
- Homepage: https://polemius.dev/recoil-persist/
- Size: 1.24 MB
- Stars: 351
- Watchers: 6
- Forks: 40
- Open Issues: 32
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Recoil Persist
Tiny module for [recoil](https://recoiljs.org) to store and sync state to
`Storage`. It is only 354 bytes (minified and gzipped). No dependencies.
[Size Limit](https://github.com/ai/size-limit) controls the size.
[Demo](https://polemius.dev/recoil-persist/)
If you are using recoil-persist with version 1.x.x please check
[migration guide](https://github.com/polemius/recoil-persist#migration-from-version-1xx-to-2xx)
to version 2.x.x.
```js
import React from 'react'
import ReactDOM from 'react-dom'
import App from './App'
import { atom, RecoilRoot, useRecoilState } from 'recoil'
import { recoilPersist } from 'recoil-persist'
const { persistAtom } = recoilPersist()
const counterState = atom({
key: 'count',
default: 0,
effects_UNSTABLE: [persistAtom],
})
function App() {
const [count, setCount] = useRecoilState(counterState)
return (
Counter: {count}
setCount(count + 1)}>Increase
setCount(count - 1)}>Decrease
)
}
ReactDOM.render(
,
document.getElementById('root'),
)
```
## Install
```
npm install recoil-persist
```
or
```
yarn add recoil-persist
```
Now you could add persisting a state to your app:
```diff
import React from 'react';
import ReactDOM from 'react-dom';
import App from './App';
import { RecoilRoot } from "recoil";
+import { recoilPersist } from 'recoil-persist'
+const { persistAtom } = recoilPersist()
const counterState = atom({
key: 'count',
default: 0,
+ effects_UNSTABLE: [persistAtom],
})
function App() {
const [count, setCount] = useRecoilState(counterState)
return (
Counter: {count}
setCount(count + 1)}>Increase
setCount(count - 1)}>Decrease
)
}
ReactDOM.render(
,
document.getElementById('root'),
)
```
After this each changes in atom will be store and sync to `localStorage`.
## Usage
```js
import { recoilPersist } from 'recoil-persist'
const { persistAtom } = recoilPersist({
key: 'recoil-persist', // this key is using to store data in local storage
storage: localStorage, // configure which storage will be used to store the data
converter: JSON // configure how values will be serialized/deserialized in storage
})
```
## 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.
```js
const defaultValue = [{ id: 1 }]
export const recoilTest = atom<{ id: number }[]>({
key: "recoilTest",
default: defaultValue,
effects_UNSTABLE: [persistAtom],
});
export function useSSR() {
const [isInitial, setIsInitial] = useState(true);
const [value, setValue] = useRecoilState(recoilTest);
useEffect(() => {
setIsInitial(false);
}, []);
return [isInitial ? defaultValue : value, setValue] as const;
}
export default function Component() {
const [text, setText] = useSSR();
// rest of the code
}
```
## API
### recoilPersist(config)
#### config parameter
```js
type config.key = String
```
Default value of `config.key` is `recoil-persist`. This key is using to store
data in storage.
```js
type config.storage = Storage
```
Set `config.storage` with `sessionStorage` or other `Storage` implementation to
change storage target. Otherwise `localStorage` is used (default).
```js
type config.converter = {
stringify: (value: any) => string
parse: (value: string) => any
}
```
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:
```js
{
parse: (value) => JSON.parse(value, myCustomReviver),
stringify: (value) => JSON.stringify(value, myCustomReplacer)
};
```
## 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:
```diff
import React from 'react';
import ReactDOM from 'react-dom';
import App from './App';
import { RecoilRoot } from "recoil";
import { recoilPersist } from 'recoil-persist' // import stay the same
const {
- RecoilPersist,
- updateState
+ persistAtom
} = recoilPersist(
- ['count'], // no need for specifying atoms keys
{
key: 'recoil-persist', // configuration stay the same too
storage: localStorage
}
)
const counterState = atom({
key: 'count',
default: 0,
- persistence_UNSTABLE: { // Please remove persistence_UNSTABLE from atom definition
- type: 'log',
- },
+ effects_UNSTABLE: [persistAtom], // Please add effects_UNSTABLE key to atom definition
})
function App() {
const [count, setCount] = useRecoilState(counterState)
return (
Counter: {count}
setCount(count + 1)}>Increase
setCount(count - 1)}>Decrease
)
}
ReactDOM.render(
- updateState({set})>
+ // Please remove updateState function from initiallizeState
- // and also remove RecoilPersist component
,
document.getElementById('root')
);
```
## Demo
```
$ git clone [email protected]:polemius/recoil-persist.git
$ cd recoil-persist
$ npm install
$ npm run start
```
Please open [localhost:1234](http://localhost:1234).