Skip to main content
New project sponsor 🪝Hookdeck: Serverless infrastructure for event-driven architecture. Learn more.

Upgrading from 1.x.x to 2.x.x

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

If you are using v1.x.x then this guide can help you.

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 tested 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.md)

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.

Customising your Catalog​

Customizing your catalog is not currently supported in v2, although this is on our roadmap (July 2024).

Generator plugins​

EventCatalog v1 supports generators (from EventBridge and AsyncAPI).

EventCatalog v2 does not support these yet and are on the roadmap (July 2024).

Missing components​

Components from v1 has not yet been implemented.

Any other issues?​

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