The Strapi Config Sync Plugin

#strapi #javascript #plugins #migration

Learn how you can use Config Sync plugin to migrate your config data across environments using the CLI or Strapi admin panel.

Author: Boaz Poolman

My name is Boaz Poolman. I’m a 25-year-old Software Developer from the Netherlands. For the last five (5) years, I’ve been working at a digital agency in Amsterdam, building websites with Drupal as the CMS. In my search to find a good Javascript alternative for Drupal, I found Strapi in 2019 and loved it. Since then, I’ve dedicated my free time to help make Strapi more powerful by writing open-source plugins to extend its functionality. Today, I’m happy to share with you a plugin I’m very excited about: config-sync.

Why I Built the Config Sync Plugin

When you use Strapi in large scale projects, with a team of multiple developers and a setup of multiple environments, you’ll soon enough find that there is no in-built way to share your config data across those environments (yet). I found that I was not the only one encountering this as there already was a Github issue and a roadmap ticket about the topic. I decided to implement this feature myself.

The primary goal of the plugin is to give the developer of any Strapi project the tools to export and import config data to JSON files so they can be moved across environments. This allows for better developer collaboration, easy auto deployment, and consistent test databases.

How Does It Work?

The idea is pretty simple: export the data on one environment; import on the other. But what’s happening behind the scenes? I’ll explain here.

In Strapi, we have loads of configuration data, some of which will be written in config files. For example, the database config, plugins config, server config, etc., are written in the config directory. These config files are easy to work with during deployment. You just have to add them to your version control (git) and you are ready to deploy (pull) them on any other environment.

Apart from the config files, some of Strapi’s configuration data is stored in the database. And that’s where it becomes tricky, as you can’t just add database records to version control and deploy them across environments. It requires special work to continuously migrate database records across different databases. And that’s exactly the gap that this plugin is trying to fill.

Having said that, this plugin is not for all your database records. It is really meant for those config tables of which the records are mainly created/updated by the developer, not by the client. You are free to use this plugin for any table you want, but by default, 4 tables are tracked:

Admin role (and permissions)
User role (and permissions)
Core store
I18n locale

How Can I Use It?

Now that you have a basic understanding of what this plugin does and why, it is time to figure out how you can utilize it in your project. After installation, you are able to export, import, and see the diff of the config. What does that actually mean?

Once you’ve installed the plugin, the first thing you have to do is run the initial export. This will create a directory config/sync in which a JSON file will be created for each record of the registered tables (by default 4). Now, you’ll have a directory full of JSON files you can play with.

Once exported, each change to the file or the record will be tracked. That means you can now do one of two things:

Change the file(s) and run an import. You have now imported from filesystem -> database.
Change the record(s) and run an export. You have now exported from database -> filesystem.

This is what the plugin is all about: exporting and importing continuously.

After building a new feature locally, you will run an export to make sure all the config will be added to version control. And when you’re deploying, you will pull the code and afterwards import the config, making sure the database is up to date with the latest changes. With this, you can fully automate the deployment workflow of your database configs.

Another feature the plugin offers is the diff feature. With the diff feature, you can see the exact difference between the database and the config/sync directory. That way, you can inspect the changes you have made before exporting them, allowing you to export only specific configs of which you know for sure you want to deploy them.

Next Steps

The config-sync plugin is one of three plugins I have made open source for Strapi. The other two are url-alias and sitemap. With the release of Strapi v4.3, we now have Typescript support and the next step will probably be to migrate all of these plugins to be written in Typescript.

For the config-sync plugin specifically, I would love to have environment specific configs, allowing you to have different configs for staging/acceptance/production. This is not really a big issue yet, but as soon as we start getting more complex plugins that store their config in the database this can become very crucial. There is an issue for that on the GitHub repo.

Apart from that, I’m always looking for new cool stuff to build so if you want to collaborate or just brainstorm with me about Strapi plugin don’t hesitate to ping me in the Strapi Discord, username boazpoolman#3868.

How Can You Contribute?

The config-sync plugin is 100% open source and hosted on Github. If you find a bug or missing feature, feel free to create an issue. And if you’re really up for a challenge, you could try and pick up one of the open issues by creating and sending me a PR on the repo. I really love to collaborate with other developers and make this a joined effort.

Here are relevant links you should check out: