Warning This repository is now merged into the monorepo of analytics-react-native. For any issues or questions go here. The
@segment/sovran-react-nativeNPM package will still be published and maintained, no changes are expected code wise.
A cross-platform lightweight local state management system designed for React Native.
Redux is a great global state management tool for React, but it's not a good fit when you need to have local state management at different scope levels.
The main advantages of Sovran vs Redux are:
- Sovran is lightweight and simple to use. Subscribing and dispatching actions is easy to setup.
- Sovran can manage state at different scope levels. From global to local to a single object.
- Sovran is designed to be used with React Native so it supports dispatching actions via the bridge native -> RN
npm install @segment/sovran-react-nativeTo use in JS/TS you just need to use createStore to create a sovran object.
import{createStore}from'@segment/sovran-react-native';interfaceState{count: number;}// Create the sovran store with our type and initial stateconststore=createStore<State>({count: 0,});createStore accepts any object as a state.
You only need to pass the initial state as a parameter.
Returns a Store object:
The returned store object has the following methods:
Subscribes a listener to updates on the store:
constunsubscribe=store.subscribe((newState: State)=>{// do something with the new stateconsole.log(newState);});// When you want to get rid of the listenerunsubscribe();Dispatches an action to modify the state, actions can be async:
Remember to keep actions as pure functions.
store.dispatch((state: State): State=>{return{
...state,count: state.count+1,}});Returns the current state on the store:
constcurrentState: State=store.getState();Sovran supports dispatching actions from native to RN. Very useful for brownfield apps.
To use this feature you first need to register which stores will listen to native updates and which actions can be sent from native:
import{createStore,registerBridgeStore}from'@segment/sovran-react-native';interfaceMessageQueue{messages: string[];}// Create the sovran store with our type and initial stateconstmessages=createStore<MessageQueue>({messages: [],});// Action to add new eventsconstaddMessage=(message: Message)=>(state: MessageQueue)=>{messages: [...state.messages,message]};// Register the store to listen to native eventsregisterBridgeStore({// Sets which store object is listenningstore: messages,// Defines which action types can be sent from native and how to handle themactions: {'add-message': addMessage,},});Now you are ready to send updates from native code!
(Supports both Objective-C and Swift)
@import React;
@import sovran_react_native;
// ...
[Sovran dispatchWithAction:@"add-message"payload:@{ @"origin": @"Native", @"message": @"Hello from Objective-C!" }];(Supports both Java and Kotlin)
importcom.sovranreactnative.Sovran;
publicclassMainApplicationextendsApplicationimplementsReactApplication {
privateSovransovran = newSovran();
privatefinalReactNativeHostmReactNativeHost =
newReactNativeHost(this) {
// Due to how Android registers modules for RN make sure you instantiate the Sovran Module package first and use the same one when you register it in you MainApplication@OverrideprotectedList<ReactPackage> getPackages() {
@SuppressWarnings("UnnecessaryLocalVariable")
List<ReactPackage> packages = newPackageList(this).getPackages();
// Register the same sovran objectpackages.add(sovran);
returnpackages;
}
// ...Map<String, String> payload = newHashMap<>();
payload.put("origin", "Native"); payload.put("message", "HellofromJava/Kotlin!"); sovran.dispatch("add-message", payload);
//...Check out the Example project for a more in depth use case in an RN project!
See the contributing guide to learn how to contribute to the repository and the development workflow.
MIT