Recoil Sync Library

The recoil-sync NPM package provides an add-on library to help synchronize Recoil state with external systems. Simple asynchronous data queries can be implemented via selectors or useEffect(), or atom effects can be used for bi-directional syncing of individual atoms. The recoil-sync add-on package provides some additional functionality:

• Batching Atomic Transactions - Updates for multiple atoms can be batched together as a single transaction with the external system. This can be important if an atomic transaction is required for consistent state of related atoms.
• Abstract and Flexible - This API allows users to specify what atoms to sync separately from describing the mechanism of how to sync. This allows components to use atoms and sync with different systems in different environments without changing their implementation. For example, a component may use atoms that persist to the URL when used in a stand-alone tool while persisting to a custom user database when embedded in another tool.
• Validation and Backward Compatibility - When dealing with state from external sources it is important to validate the input. When state is persisted beyond the lifetime of an app it can also be important to consider backward compatibility of previous versions of state. recoil-sync and refine help provide this functionality.
• Complex Mapping of Atoms to External Storage - There may not be a one-to-one mapping between atoms and external storage items. Atoms may migrate to use newer versions of items, may pull props from multiple items, just a piece of some compound state, or other complex mappings.
• Sync with React Hooks or Props - This library enables syncing atoms with React hooks or props that are not accessible from atom effects.

The recoil-sync library also provides built-in implementations for external stores, such as syncing with the browser URL.

---

The basic idea is that a syncEffect() can be added to each atom that you wish to sync, and then a <RecoilSync> is added inside your <RecoilRoot> to specify how to sync those atoms. You can use built-in stores such as <RecoilURLSyncJSON>, make your own, or even sync different groups of atoms with different stores.

Example

URL Persistence

Here is a simple example syncing an atom with the browser URL:

const currentUserState = atom<number>({
  key: 'CurrentUser',
  default: 0,
  effects: [
    syncEffect({ refine: number() }),
  ],
});

Then, at the root of your application, simply include <RecoilURLSyncJSON> to sync all of those tagged atoms with the URL

function MyApp() {
  return (
    <RecoilRoot>
      <RecoilURLSyncJSON location={{part: 'queryParams'}}>
        ...
      </RecoilURLSyncJSON>
    </RecoilRoot>
  )
}

That's it! Now this atom will initialize its state based on the URL during initial load, any state mutations will update the URL, and changes in the URL (such as the back button) will update the atom. See more examples in the Sync Effect, Store Implementation, and URL Persistence guides.

Installation

Please see the Recoil installation guide and add recoil-sync as an additional dependency.

recoil-sync also uses the refine library for type refinement and input validation.