https://github.com/agilgur5/mst-persist
Persist and hydrate MobX-state-tree stores (in < 100 LoC)
https://github.com/agilgur5/mst-persist
async asyncstorage hydrate local localforage localstorage mobx mobx-state-tree mst persist persistence session sessionstorage state state-tree storage tree
Last synced: about 1 month ago
JSON representation
Persist and hydrate MobX-state-tree stores (in < 100 LoC)
- Host: GitHub
- URL: https://github.com/agilgur5/mst-persist
- Owner: agilgur5
- License: other
- Created: 2019-05-19T09:30:26.000Z (almost 6 years ago)
- Default Branch: main
- Last Pushed: 2023-07-19T07:07:48.000Z (almost 2 years ago)
- Last Synced: 2025-03-24T10:55:36.657Z (about 2 months ago)
- Topics: async, asyncstorage, hydrate, local, localforage, localstorage, mobx, mobx-state-tree, mst, persist, persistence, session, sessionstorage, state, state-tree, storage, tree
- Language: TypeScript
- Homepage:
- Size: 322 KB
- Stars: 86
- Watchers: 4
- Forks: 17
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# mst-persist
[](https://npmjs.org/package/mst-persist)
[](https://github.com/agilgur5/mst-persist/releases)
[](https://github.com/agilgur5/mst-persist/commits/master)
[](https://npmjs.org/package/mst-persist)
[](https://npmjs.org/package/mst-persist)
[](https://npmjs.org/package/mst-persist)
[](https://npmjs.org/package/mst-persist)
[](src/index.ts)
[](https://github.com/agilgur5/mst-persist/actions/workflows/ci.yml?query=branch%3Amain)
[](https://codecov.io/gh/agilgur5/mst-persist)
Persist and hydrate [MobX-state-tree](https://github.com/mobxjs/mobx-state-tree) stores.
## Installation
```sh
npm i -S mst-persist
```
## Usage
```javascript
import { types } from 'mobx-state-tree'
import localForage from 'localForage'
import { persist } from 'mst-persist'
const SomeStore = types.model('Store', {
name: 'John Doe',
age: 32
})
const someStore = SomeStore.create()
persist('some', someStore, {
storage: localForage, // or AsyncStorage in react-native.
// default: localStorage
jsonify: false // if you use AsyncStorage, this shoud be true
// default: true
whitelist: ['name'] // only these keys will be persisted
}).then(() => console.log('someStore has been hydrated'))
```
### API
#### `persist(key, store, options)`
- arguments
- **key** *string* The key of your storage engine that you want to persist to.
- **store** *[MST](https://github.com/mobxjs/mobx-state-tree) store* The store to be persisted.
- **options** *object* Additional configuration options.
- **storage** *[localForage](https://github.com/localForage/localForage) / [AsyncStorage](https://github.com/react-native-community/async-storage) / [localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage)*
Any Storage Engine that has a Promise-style API similar to [`localForage`](https://github.com/localForage/localForage).
The default is [`localStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage), which has a built-in adaptor to make it support Promises.
For React Native, one may configure [`AsyncStorage`](https://github.com/react-native-community/async-storage) instead.
Any of [`redux-persist`'s Storage Engines](https://github.com/rt2zz/redux-persist#storage-engines) should also be compatible with `mst-persist`.
- **jsonify** *bool* Enables serialization as JSON (default: `true`).
- **whitelist** *Array\* Only these keys will be persisted (defaults to all keys).
- **blacklist** *Array\* These keys will not be persisted (defaults to all keys).
- returns a void Promise
### Node and Server-Side Rendering (SSR) Usage
Node environments are supported so long as you configure a Storage Engine that supports Node, such as [`redux-persist-node-storage`](https://github.com/pellejacobs/redux-persist-node-storage), [`redux-persist-cookie-storage`](https://github.com/abersager/redux-persist-cookie-storage), etc.
This allows you to hydrate your store server-side.
For SSR though, you may not want to hydrate your store server-side, so in that case you can call `persist` conditionally:
```javascript
if (typeof window !== 'undefined') { // window is undefined in Node
persist(...)
}
```
With this conditional check, your store will only be hydrated client-side.
## Examples
None yet, but can take a look at [agilgur5/react-native-manga-reader-app](https://github.com/agilgur5/react-native-manga-reader-app) which uses it in production.
Can view the commit that implements it [here](https://github.com/agilgur5/react-native-manga-reader-app/pull/2/commits/286725f417d321f25d16ee3858b0e7e6b7886e77).
Can also view some of the internal [tests](test/).
## How it works
Basically just a small wrapper around MST's [`onSnapshot` and `applySnapshot`](https://github.com/mobxjs/mobx-state-tree#snapshots).
The source code is currently shorter than this README, so [take a look under the hood](https://github.com/agilgur5/mst-persist/tree/master/src)! :)
## Credits
Inspiration for parts of the code and API came from [`redux-persist`](https://github.com/rt2zz/redux-persist), [`mobx-persist`](https://github.com/pinqy520/mobx-persist), and [this MST persist PoC gist](https://gist.github.com/benjick/c48dd2db575e79c7b0b1043de4556ebc)