Storing values

There are several forms of storage available in modern browsers. Here is a break-down of them and when they should be preferred.

In-Memory

In general, in memory storage refers to anything stored in Javascript that is not part of a persistent storage. In general, values stored in memory remain valid for:

No in-memory values survive page reload. For values that need to persist across a page-reload (and note that this means browser page refresh and not merely in-application navigation), use persistent storage.

Variables

Simplest way to store a value. Looks something like:

const value = /* some value */;

The lifecycle of this variable depends on it's scope (opens in a new tab). In general, it's preferable to store values in the narrowest scope possible, that is, prefer function-scope to module-scope and module-scope to global-scope.

Inside React, it is generally preferrable to use simple variables unless recomputing the variable is expensive. For example:

const name = `${patient.first} ${patient.last}`;

Is likely to be fine, unless operating on a large list of items or performing potentially complicated operations.

React State

const [value, setValue] = useState(/* some value */);

Sometimes we need variables which maintain consistent values across component renders. Where these values are component-specific, useState() allows us to store a component-specific version of a value that only gets updated when it's setter is called.

React Memo

const value = useMemo(() => /* some computation */, [dependencies]);

Not exactly "storage", but like useState() provides a consistent value until a condition holds (a value in the dependency array changes). Useful for infrequently computed or expensive to compute state.

React Context

React's Context mechanism can be useful for storing data that needs to be shared solely by components in the same React tree; for example, values that are shared by multiple components in the same microfrontend might benefit from using React's context. React Context provides values with a scope beyond just the lifecycle of a single component, but which are not maintained in the absence of the React tree. For example, a form might use React Context to store all the "current" values of all the input components on the form.

// in a parent module
const MyContext = createContext(/* some value */);
 
// inside a parent component
return (
  <MyContext.Provider value={/* some value */}>{children}</MyContext.Provider>
);
 
// inside a child component
const myValue = useContext(MyContext);

This is useful for ensuring that an entire React tree has a consistent version of state.

Global Store

Provided by @openmrs/esm-framework (and, specifically, esm-global); this gives us access to Zustand stores (opens in a new tab). This is useful for storing values that are shared across more than one component and need to be consistent across them. Note that while the underlying implementation uses Zustand, it is preferable to use the framework-provided API (opens in a new tab), e.g.,

// outside of a component
const userStore = createGlobalStore<UserStore>('userStore', { user: null });
 
// inside a component
const user = useStore<UserStore, User | null>(userStore, state => state.user);
 
// at some other point
userStore.set((state) => state.user = /* value from somewhere */);

Updating the store using set() will update all variables subscribed to the store, including (like in the example) user.

Persistent Storage

Persistent storage refers to any storage mechanism that persists beyond a render of the single-page.

The Backend

At least while online, storing persistent data to the backend should be the default. This is generally done through using the REST or FHIR APIs for OpenMRS.

Session Storage

This provides a Storage (opens in a new tab) API for values that persist across a page session. Page sessions generally persist as long as a single browser tab. This should be the preferred storage mechanism for values that need to persist across a page reload boundary.

Local Storage

This provides a Storage (opens in a new tab) API for values that persist until they are changed. They are specific to a web origin, but apply to all tabs and all pages. This is useful for storing user application-level preferences (e.g., language), but should not be used unless the value should be associated with the user-and-browser combination.