For the past couple of years, my involvement with the Gutenberg project in WordPress has frequently taken me into the innards of @wordpress/data.  I’ve had to use it for projects integrating with the new WordPress Block Editor (Gutenberg), new interfaces and user experiences utilizing the new WordPress JavaScript packages, and I’ve also been directly involved with various improvements via contributions to the package itself.

In that time, I’ve had the opportunity to learn quite a bit about this package and the promise it holds for data and state management in the WordPress future and at the same time I’ve also observed the apparent scarcity of really exhaustive and thorough documentation about it.  This has surfaced multiple times as I’ve interacted with teammates or various WordPress developers who have various questions about how to use it. 

So, this series of posts is something I’ve been working on for a while that I hope will help close the gap for more people on understanding what @wordpress/data is and how to use it. Since there’s a lot of material to cover, I’m splitting this series up into smaller chunks and publishing each post in the series over time. 

Before We Begin:

I think it’s important to highlight a few things before you begin reading this series:

For brevity, I’ll be using wp.data as the label for the WordPress data api and library in this series of posts. Incidentally, this is also the form it takes when enqueued as a part of the wp global in the WordPress environment!

I’ll be referencing some examples I built on codesandbox.io throughout this series. You can fork them and use the forks for the various exercises I sprinkle through this series to help with learning the various concepts. Since the internet is rife with “todo” app examples, I decided I’d do something different and our example app has a basic interface for adding products to a product directory and a companion view for displaying them to the user. It also has a very basic cart that the user can add products to or remove from. All code is written in ESNext. If some of the syntax is newer to you, this article can help with deciphering it.

I’m assuming basic familiarity with React and various react concepts. This series is not an introduction to React.

Having some familiarity with Redux and React Redux concepts is a plus, but not a requirement for reading this series. I only mention it because if you are super familiar with redux and react redux you may find parts of this series a bit redundant. Feel free to skip those parts, however, keep in mind that while wp.data and redux share a lot of similarities, there are some key differences (which I’ll highlight in the next post).

Having some familiarity with generators, what they are and how to use them is a plus. If you’ve never encountered generators before, you can read about them on MDN. This article also gives a basic overview.

I’m assuming a basic familiarity with using package management (npm or yarn) and I’m not addressing how you might implement what you’d learn here in any build tool setup you might use for a WordPress plugin. The concepts you learn in this series will be transferable to anywhere you use wp.data whether it be consuming the package directly or via the wp.data external in WordPress core or a plugin.

I won’t be doing exhaustive descriptions of all the various registered data stores in a given WordPress editor instance. This series focuses on the core concepts of using the wp.data api and with that knowledge, you should be able to better understand and utilize those stores directly.

Ask Questions!
I’ve intentionally tried to keep each post in the series fairly short and to the point. In the process, there may be concepts or terms I use that might be a bit confusing or you might want some more details. If that happens for you, ask questions in the comments! I’ll be using the comments to help inform revisions to the original posts so it’ll be very valuable to get your feedback.

Since I’m publishing this series over time, in the Table of Contents of the series you will see all the posts in the series, but some of them will not be published yet. The general themes I intend to cover in this series (over many posts) are:

• What is wp.data and why would you want to use it.
• How to register a custom store in wp.data.
• Interfacing with your custom store.
• What is the wp.data registry and how do you use it.
• Tips on debugging wp.data and various debugging tools available.
• Testing your custom store and interfaces to the store.

With that out of the way, let’s get started on our first post in the series!

Series Navigation

What is WordPress Data?