## Table of Contents
- [Features](#-features)
- [Installation](#-installation)
- [Requirements](#-requirements)
- [Motivation](#-motivation)
- [CLI](#-command-line-interface-cli)
- [Admin panel](#%EF%B8%8F-admin-panel-gui)
- [Usage / Workflow](#%EF%B8%8F-usage--workflow)
- [Config types](#-config-types)
- [Naming convention](#-naming-convention)
- [Settings](#-settings)
## ✨ Features
- **CLI** - `config-sync` CLI for syncing the config from the command line
- **GUI** - Settings page for syncing the config in Strapi admin
- **Partial sync** - Import or export only specific portions of config
- **Custom types** - Include your custom collection types in the sync process
- **Import on bootstrap** - Easy automated deployment with `importOnBootstrap`
- **Exclusion** - Exclude single config entries or all entries of a given type
- **Diff viewer** - A git-style diff viewer to inspect the config changes
## ⏳ Installation
Install the plugin in your Strapi project.
```bash
# using yarn
yarn add strapi-plugin-config-sync
# using npm
npm install strapi-plugin-config-sync --save
```
Add the export path to the `watchIgnoreFiles` list in the `config/admin.js` file.
This way your app won't reload when you export the config in development.
##### `config/admin.js`:
```
module.exports = ({ env }) => ({
// ...
watchIgnoreFiles: [
'**/config/sync/**',
],
});
```
After successful installation you have to rebuild the admin UI so it'll include this plugin. To rebuild and restart Strapi run:
```bash
# using yarn
yarn build
yarn develop
# using npm
npm run build
npm run develop
```
The **Config Sync** plugin should now appear in the **Settings** section of your Strapi app.
To start tracking your config changes you have to make the first export. This will dump all your configuration data to the `/config/sync` directory. You can export either through [the CLI](#-command-line-interface-cli) or [Strapi admin panel](#%EF%B8%8F-admin-panel-gui)
Enjoy 🎉
## 🖐 Requirements
Complete installation requirements are the exact same as for Strapi itself and can be found in the [Strapi documentation](https://strapi.io/documentation).
**Supported Strapi versions**:
- Strapi 4.3.2 (recently tested)
- Strapi ^4.x (use `strapi-plugin-config-sync@^1.0.0`)
- Strapi ^3.4.x (use `strapi-plugin-config-sync@0.1.6`)
## 💡 Motivation
In Strapi we come across what I would call config types. These are models of which the records are stored in our database, just like content types. Though the big difference here is that your code ofter relies on the database records of these types.
Having said that, it makes sense that these records can be exported, added to git, and be migrated across environments. This way we can make sure we have all the data our code relies on, on each environment.
Examples of these types are:
- Admin roles _(admin::role)_
- User roles _(plugin::users-permissions.role)_
- Admin settings _(strapi::core-store)_
- I18n locale _(plugin::i18n.locale)_
This plugin gives you the tools to sync this data. You can export the data as JSON files on one env, and import them on every other env. By writing this data as JSON files you can easily track them in your version control system (git).
_With great power comes great responsibility - Spider-Man_
## 🔌 Command line interface (CLI)
Add the `config-sync` command as a script to the `package.json` of your Strapi project:
```
"scripts": {
// ...
"cs": "config-sync"
},
```
You can now run all the `config-sync` commands like this:
```bash
# using yarn
yarn cs --help
# using npm
npm run cs --help
```
### ⬆️ Import ⬇️ Export
> _Command:_ `import` _Alias:_ `i`
>
> _Command:_ `export` _Alias:_ `e`
These commands are used to sync the config in your Strapi project.
_Example:_
```bash
# using yarn
yarn cs import
yarn cs export
# using npm
npm run cs import
npm run cs export
```
##### Flag: `-y`, `--yes`
Use this flag to skip the confirm prompt and go straight to syncing the config.
```bash
[command] --yes
```
##### Flag: `-t`, `--type`
Use this flag to specify the type of config you want to sync.
```bash
[command] --type user-role
```
##### Flag: `-p`, `--partial`
Use this flag to sync a specific set of configs by giving the CLI a comma-separated string of config names.
```bash
[command] --partial user-role.public,i18n-locale.en
```
##### Flag: `-f`, `--force`
If you're using the soft setting to gracefully import config, you can use this flag to ignore the setting for the current command and forcefully import all changes anyway.
```bash
[command] --force
```
### ↔️ Diff
> _Command:_ `diff` | _Alias:_ `d`
This command is used to see the difference between the config as found in the sync directory, and the config as found in the database.
_Example:_
```bash
# using yarn
yarn cs diff
# using npm
npm run cs diff
```
##### Argument: `