Skip to main content

Installation

License: Dual-license

The EventCatalog Federation plugin is designed for your main catalog.

This plugin will allow you to merge multiple EventCatalog instances into a single catalog.

Prerequisites​

Installation​

Run the command below to install the EventCatalog Federation plugin.

npm i @eventcatalog/generator-federation

Configuration​

Configure the plugin in your eventcatalog.config.js file.

Add the plugin to the generators.

eventcatalog.config.js
// ...
generators: [
    [
      '@eventcatalog/generator-federation',
      {
        // Pulling information from a GitHub repository, (generator supports any Git source e.g GitLab, Bitbucket, etc)
        source: 'git@github.com:event-catalog/generators.git',

        // specifying the branch to pull from (default is main)
        branch: 'main',

        // optional (specify which files you want to copy from the repository)
        copy: [
          {
            // importing content from the customer-experience-team catalog
            content: 'examples/generator-federation/basic/customer-experience-team/services',
            // specify the target path in your main catalog, here we are importing the services from the customer-experience-team catalog
            destination: path.resolve(__dirname, 'services')
          },
          {
            // importing content from the customer-experience-team catalog
            content: 'examples/generator-federation/basic/customer-experience-team/teams',
            // specify the target path in your main catalog, here we are importing the services from the customer-experience-team catalog
            destination: path.resolve(__dirname, 'teams')
          },
          {
            // importing content from the customer-experience-team catalog
            content: 'examples/generator-federation/basic/customer-experience-team/users',
            // specify the target path in your main catalog, here we are importing the services from the customer-experience-team catalog
            destination: path.resolve(__dirname, 'users')
          }
        ],

        // optional, if you want to merge and override any conflicts then set to true (default is false)
        override: true,

        // optional, if you want the plugin to error 
        // if there are duplicate resources in your 
        // main catalog then set to true (default is false)
        enforceUniqueResources: true
      },
    ],
    // Payment Team
    // When no `copy` values are provided, the plugin will copy eventcatalog files for you.
    [
      '@eventcatalog/generator-federation',
      {
        // Pulling information from a GitHub repository
        source: 'git@github.com:event-catalog/generators.git',

        // specifying the directory of the eventcatalog in your project (default it the root directory)
        // This example clones the generators repository, and looks for the eventcatalog in the my-project-eventcatalog directory
        sourceRootDir: 'my-project-eventcatalog'

        // specifying the branch to pull from (default is main)
        branch: 'main',

        // optional, if you want to merge and override any conflicts then set to true (default is false)
        override: true,

        // optional, if you want the plugin to error 
        // if there are duplicate resources in your 
        // main catalog then set to true (default is false)
        enforceUniqueResources: true
      },
    ],
  ],

Configure license key​

The EventCatalog Federation plugin requires a license key to work with EventCatalog.

You can get a trial license key from EventCatalog Cloud.

You have a few options for setting the license key:

  1. Setting license key in .env file (recommended)
  2. Setting license key in eventcatalog.config.js
Added in eventcatalog@2.35.4

Create a .env file in the root of your project and add the following:

.env
EVENTCATALOG_LICENSE_KEY_FEDERATION=your-license-key
Using an older version of EventCatalog?

If you are using an older version of EventCatalog that does not support the .env file, you can just export the license key as an environment variable.

Setting license key in environment variables
export EVENTCATALOG_LICENSE_KEY_FEDERATION=your-license-key

2. Setting license key in eventcatalog.config.js​

If you prefer, you can set the license key in the eventcatalog.config.js file using the licenseKey property in the EventCatalog Federation plugin.

eventcatalog.config.js
export default {
  generators: [
    [
      '@eventcatalog/generator-federation',
      {
        licenseKey: '[INSERT_YOUR_LICENSE_KEY]', // or process.env.EVENTCATALOG_LICENSE_KEY_FEDERATION
      },
    ],
  ],
};

White listing EventCatalog domains​

If you are behind a firewall you will need to white list the domain https://api.eventcatalog.cloud in your firewall. This is because the plugin needs to verify your license key.

Run the generator​

Once you have configured the plugin and license key you can run the generator.

npm run generate

View your catalog​

Run your catalog locally to see the changes.

npm run dev

Any questions or need help?​

If you get stuck, find an issue or need help, please raise an issue on GitHub or join our Discord community.