Chapter 9: Composable Plugins – Create Your First Plugin

In this chapter, we'll learn how to create a Rematch plugin that will be used on our Amazhop website, warning us when we dispatch any action with a wrong payload value. Also, we'll learn how we can test this plugin using using Jest, as well as how we can build a module with the latest bundling technologies for publishing it to NPM, making it open source to everyone.

In this chapter, we'll cover the following topics:

• Preparing the environment
• Creating our plugin
• Testing our plugin
• Publishing to NPM

By the end of the chapter, you will understand how to create any Rematch plugin from the ground up with tools for bundling libraries such as Tsdx. You'll also learn how to correctly test these plugins using Jest and how we can use features that Yarn or NPM offer to test these packages locally. Also, you'll learn how to successfully publish a Rematch plugin to NPM.

Technical requirements

To follow along with this chapter, you will need the following:

• Basic knowledge of Vanilla JavaScript and ES6 features
• Basic knowledge of HTML5 features
• Node.js >= 12
• Basic knowledge of React and CSS
• A browser (Chrome or Firefox, for instance)
• A code editor (Visual Studio Code, for instance)

You can find the code for this chapter in the book's GitHub repository: https://github.com/PacktPublishing/Redux-Made-Easy-with-Rematch/tree/main/packages/chapter-9.

To get started with this chapter, we're going to use a different approach to what we did in previous chapters where we built a complete application. In this case, we're going to build a small library that is going to be published to NPM, for further usage in our Amazhop web application.

Preparing the environment

There are multiple ways of creating a library, from using an index.js file with one single format and a package.json file, to using some JavaScript files that are compiled to multiple formats and published through NPM. We will do the latter.

To compile the JavaScript files, we're going to use a zero-config CLI for package development called Tsdx (https://tsdx.io). This will help us to develop, test, and publish modern libraries with ease so we can focus on just writing our code and let Tsdx do all the complex configuration.

We can quickly bootstrap a new library in seconds, just by writing this in the terminal:

npx tsdx create typed-state-plugin

This will create a folder called typed-state-plugin/ with the basic setup we need to create our library.

This tool is going to create a file structure like this:

├── .gitignore
├── .prettierrc
├── package.json
├──...

Creating our plugin

Creating a Rematch plugin is as easy as creating an object with some properties, as you'll remember from Chapter 8, The Rematch Plugins Ecosystem. Rematch plugins accept certain properties; in this chapter, we're going to use two of them: onModel and createMiddleware.

onModel

The onModel hook is executed when the whole setup for the model is completed, that is, when the reducers and dispatchers are correctly injected and ready to use. The onModel hook is executed for each model, allowing us to pick or overwrite values from any model.

In our case, we want to save a cache of each typings property of each model. This is a required step for our plugin because we'll need to access these typings properties later to use the plugin in the createMiddleware hook.

Let's next add to the exposed property a new property called onModel:

onModel: (model) => {
  TYPINGS_CACHE[model.name] = model.typings;
}

The TYPINGS_CACHE variable...

Testing our plugin

Tsdx creates all the configuration we need to make our tests with Jest out of the box. As you'll remember, we used this testing framework for our Amazhop application. We'll just use the same approach.

Inside our index.test.ts file, we can add a describe() function that describes what we are going to test:

describe("Rematch Plugin Typed State", () => {})

Since we're going to use the same model in every test, we can create a constant to extend a base model for each test:

const BASE_MODEL = {
  name: 'user',
  state: {
    name: "Sergio",
    age: 23,
  },
  reducers: {
    update: (_, { name, age }) => ({
      name,
      age,
    }),
  },
};

This code is a basic Rematch model, a state with one string and one number...

Publishing to NPM

What's a symbolic link? It's a kind of file, normally hidden from us, that points to another file, much like a shortcut.

The main purpose of using symbolic links, or symlinks, is that we can link a local dependency and use it in another project. This is useful for developing new libraries or packages where we can test them in real projects.

Both Yarn and NPM can be used to make symbolic links with just one command:

~: yarn link
~: npm link

Taking the code we implemented in this chapter, in the root of our project, we can execute the yarn link command:

~: yarn link
yarn link v1.22.10
success Registered "typed-state-plugin".
info You can now run `yarn link "typed-state-plugin"` in the projects where you want to use this package and it will be used instead.
  Done in 0.07s

Magically, we'll get a symbolic link of the entire code base where we implemented the plugin and it is ready to use in our Amazhop applications...

Summary

In this chapter, we have learned how we can create from scratch any JavaScript library and how tools such as Tsdx can help us to have an easier development experience. Also, we saw a little introduction to TypeScript, and how Rematch plugins are easily created and integrated into existing code bases.

In the next chapter, we'll migrate our entire Amazhop web application to TypeScript, focusing on Rematch TypeScript helpers, which will help us to create a complete typed Rematch store with autocomplete for every reducer, effect, and even our state.