Skip to main content

Upgrade to EventCatalog v2

This guide will help you upgrade from v1 to v2 of EventCatalog.

EventCatalog v2 comes with some small breaking changes to your EventCatalog.

Still want to use v1?

Still using v1 of EventCatalog? V1 documentation can be found at https://v1.eventcatalog.dev/

You can find the code for v1 on the branch https://github.com/event-catalog/eventcatalog/tree/v1

We recommended to upgrade to v2 as support for v1 changes will be reduced.

Migrating to version 2​

EventCatalog v2 has been rewritten from the ground up. The easiest way to migrate to version 2 is following these steps:

  1. Create a new Catalog
  2. Delete the domains, services, commands and events folder.
  3. Copy your eventcatalog.config.js and domains, services, events folders into the new catalog.
  4. Add ids to all your resources (read more)
  5. If your resource are in a nested structure you need to flatten these out.
Having problems?

If you are still having issues upgrading your catalog, then please raise an issue on our GitHub repo..

Resources now require ids​

All domains, services and events need an id property in the frontmatter. EventCatalog uses this id as the slug of the page and uses it as internal references.

Example​

---
# id is now required on all resources (domains, services and messages)
id: order-service
name: Order Service
# rest of frontmatter..
---
<!-- Your markdown content -->

Resources require a flat structure​

In EventCatalog v1 you could nest your resources for example have your events or services within your domains folder. (Example /domains/services/MyService/index.mdx)

This feature is not currently supported in version 2.

Version 2 requires your domains, services and messages (commands, and events) to be in the root directory.

Change to build output​

The build output has changed from v1 from being out directory to dist directory in version 2.

Any other issues?​

If you have any issues or questions please feel free to reach us on Discord.