Skip to main content

Upgrading EventCatalog

Upgrade to latest version​

To upgrade your EventCatalog to the latest version you can run the following command in your catalog directory.

npm install @eventcatalog/core@latest

Manual upgrade​

To upgrade your EventCatalog you can find the packages @eventcatalog/core your package.json file.

{
  "name": "my-catalog",
  "version": "0.0.1",
  "private": true,
  "scripts": {
    ...
  },
  "dependencies": {
    "@eventcatalog/core": "2.4.0"
  }
}

Once you upgrade the version number, run npm install to install the latest updates.

tip

If you don't see the changes you expect, try removing the .eventcatalog-core folder, node_modules folder and install fresh again.

Having problems?​

Trying to upgrade and having issues? Try these steps

  1. Delete node_modules folder
  2. Delete .eventcatalog-core folder
  3. Delete package-lock.json (if you have one).
  4. Run npm run i
  5. Verify if issues are fixed

Still having issues?

  1. Raise an issue on GitHub about your problems and how to replicate it.
  2. Or join our Discord and add your problem to the Bugs channel.

Upgrading from v1 to v2​

If you are upgrading from EventCatalog v1 to v2 you can follow the instructions below.

Details

Upgrading from v1 to v2 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 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.

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.