The primary way in which you interact with state in wp.data is through a registered store. In this post we’re going to give an overview of the api for registering a store and then subsequent posts will dive into the specific components of the store config.

registerStore( reducerKey, options )

Every data store found in wp.data has to be registered and you can see many examples of this throughout the Gutenberg codebase. The interface via which you register a store with wp.data is via the registerStore function. Through this function you add your store to the centralized data registry.

Sidenote: Something important to mention here is that when you register a store through wp.data.registerStore, you are registering with the default registry. This has some implications that we’ll get into a later article. In nearly all cases, it’s okay to register with the default store.

The registerStore function accepts two arguments: a name to identify the module (or store), and an object with values describing  how your state is represented, mutated (or modified), and accessed. 

The first argument can be referred to by many different terms, “store namespace”, “store key”, “store name”, “module name”, “module namespace”, or even “reducer key”! To keep things simple, we’ll call this argument the store name. It must be unique and a common pattern for naming data stores is to do something like group/store_content.  The group portion of the store name here might be your plugin name, or application name etc. The store_content portion of the store name here might be what kind of data is kept in the store.

So for instance, for the WooCommerce plugin, they might use something like wc/products as a store name for a registered store that holds products. 

The second argument is a configuration or options object that contains the logic of your store represented by 5 different elements. Briefly they are referenced by the object property names: selectors, controls, resolvers, actions, initialState, and reducer (note the singular for the last one!).  At a minimum, all registered stores must be registered with a reducer that describes the shape of your state and how it changes in response to actions dispatched to your store.

The return value of registerStore is a Redux-like store object with the following methods:

• getState(): Returns the state value of the registered reducer (Redux parallel: getState)
• subscribe( listener: Function ): Registers a function called any time the value of the state changes. (Redux parallel: subscribe). Remember, Redux calls the subscribed function on every dispatched action whereas wp.data only calls the function when the state changes.
• dispatch( action: Object ): Given an action object, calls the registered reducer and updates the state value. (Redux parallel: dispatch)

Typically, and in most cases you won’t need to utilize the return values of your registered store unless there are some more low-level things you need to do with the store or if you want to use wp.data with something other than React. So for the purpose of this series, we’re not going to spend time on these and instead will focus on the common public interfaces for binding store functionality and state to your react app.

Here’s how registering a store typically appears in code:

import { registerStore } from '@wordpress/data';
 
// bringing in the api pieces from other files in my app
import * as selectors from './selectors';
import * as actions from './actions';
import * as resolvers from './resolvers';
import reducer from './reducer';
import controls from './controls';
 
const STORE_NAME = 'myAwesomeApp/data';
 
registerStore(
 STORE_NAME,
 {
   selectors,
   actions,
   resolvers,
   reducer,
   controls
 }
);
 
export { STORE_NAME };

Now that we’ve done an overview of what you use to register a store, the next post in this series will take a closer look at the individual properties of a store.

Series Navigation

What is WordPress Data?WordPress Data Interlude: Let’s talk Apps