Skip to main content

Upgrade to EventCatalog v3

This guide will help you upgrade from v2 to v3 of EventCatalog. (Missed the announcement? Read the blog post to find out what's new.)

Need to see the v2 docs? Visit this older version of the docs site. EventCatalog V2 will continue to get security updates, but new features and improvements will only be available in v3.

Upgrade EventCatalog​

Update your project’s version of EventCatalog to the latest version using your package manager:

npm install @eventcatalog/core@latest

Problems upgrading? Try resetting your project.

Deprecated​

The following deprecated features are no longer supported and are no longer documented. Please update your project accordingly.

Some deprecated features may temporarily continue to function until they are completely removed. Others may silently have no effect, or throw an error prompting you to update your code.

Deprecated: Visualizer sidebar icon​

The visualizer vertical sidebar icon has been removed and replaced with the new navigation system.

To get to the visualizer for a resource, you will now click on the Visualizer link in the new navigation system.

Deprecated: /architecture/ pages​

The general /architecture/domains, /architecture/services and /architecture/messages pages have been removed and replaced with architecture pages per domains and service.

To get to the architecture, you will now click on the Architecture Diagram link in the new navigation system.

Deprecated: Resource sidebars​

The resource sidebar (sidebar on the right of the page) has been removed and replaced with On this page section.

We have moved the resource information into the new navigation system.

Deprecated: @eventcatalog/generator-ai package​

The AI package has been removed and replaced with the EventCatalog Assistant.

What do I need to do?​

Remove the @eventcatalog/generator-ai package from your project (if you have one) and any references to it in your generator configuration.

npm uninstall @eventcatalog/generator-ai

Removed​

The following features have now been entirely removed from the code base and can no longer be used. Some of these features may have continued to work in your project even after deprecation. Others may have silently had no effect.

Projects now containing these removed features will be unable to build, and there will no longer be any supporting documentation prompting you to remove these features.

Removed: LIST_VIEW and SIDE_VIEW navigation options​

EventCatalog v3 introduces a new navigation sidebar.

For maintainability reasons going forward we have removed the old LIST_VIEW and SIDE_VIEW navigation options.

What do I need to do?​

Remove the sidebar.type property from your eventcatalog.config.js file.

eventcatalog.config.js
module.exports = {
   docs: {
-    sidebar: {
-       type: 'LIST_VIEW'
-    }
  }
};

Removed: /docs landing page​

In EventCatalog v2 we had two homepages, one for / and one for /docs (both could be customized).

What do I need to do?​

You can removed the /pages/index.mdx file from your project (if you have one).

If you still need to customize the homepage you can create a /pages/homepage.astro file and add your own content to it.

In EventCatalog v2 we used Pagefind for search, this would run after you build your catalog and index your resources.

We have now moved to nanostores to share state across the catalog, and users no longer have to build their catalog to search.

Removed: EventCatalog Chat​

We have removed the EventCatalog Chat feature as it was in EventCatalog v2, and any model npm packages used.

We have replaced EventCatalog Chat with the EventCatalog Assistant.

What do I need to do?​

Remove the @eventcatalog/generator-ai plugin from your project (if you have one)

npm uninstall @eventcatalog/generator-ai

Remove the chat configuration from your eventcatalog.config.js file (if you have one)

eventcatalog.config.js
module.exports = {
    chat: {
      enabled: true,
-      provider: 'openai'
-      model: 'o4-mini',
    }
};

The model and provider configuration has been moved to the eventcatalog.chat.js file.

You can read more about the new AI assistant in the AI assistant documentation.

Removed: EventCatalog Chat prompts​

We have removed the EventCatalog Chat prompts in EventCatalog.

What do I need to do?​

Remove the chat-prompts directory from your project (if you have one)

rm -rf chat-prompts

We plan to support custom prompts and tools in the future.

Removed: Governance Reports​

We have removed the Governance Reports feature which used EventCatalog with AI to generate reports on your architecture. We will be reviewing better ways to support governance reports in the future but for now we have decided to remove the feature.

Breaking changes​

The following changes are considered breaking changes in EventCatalog v3. Breaking changes may or may not provide temporary backwards compatibility. If you were using these features, you may have to update your code as recommended in each entry.

Changed: Domain hierarchy changed​

Previously in EventCatalog v2 domains would show all resources within it's subdomains and services including all the messages in that service. A cascading approach was used to show the resources.

In EventCatalog v3 domains are now more explicit about what resources are within it and you have to specify the resources you want to include in the domain.

This allows us to move forward to support domain level specifications and events (in this RFC)

Changed: Authentication​

In EventCatalog v3 we introduced a new configuration variable to enable authentication, which fixes the need for catalogs running on the server without authentication required.

If you are using authentication you will need to update your eventcatalog.config.js file to enable authentication.

eventcatalog.config.js
module.exports = {
+  auth: {
+    enabled: true,
+  }
};

Changed: EventCatalog no longer supports .md files​

EventCatalog v3 no longer supports .md files and only supports .mdx files.

EventCatalog v2 would transform any .md files found in your catalog to .mdx files during the migration to v2, we have removed this going forward.

What do I need to do?​

If you have any .md files in your catalog, you will need to convert them to .mdx files. You can use the eventcatalog convert command to convert your .md files to .mdx files.

eventcatalog convert

Changed: Changelogs are disabled by default​

In EventCatalog v3 changelogs are now disabled by default. If you want to enable changelogs for your resources you will need to update your eventcatalog.config.js file.

What do I need to do?​

If you want to enable changelogs, add the changelog configuration to your eventcatalog.config.js file:

eventcatalog.config.js
module.exports = {
+  changelog: {
+    enabled: true,
+  }
};

New features​

The following new features and improvements have been added to EventCatalog v3.

New context aware navigation​

EventCatalog v2 sidebars were restricting in the way users could navigate their resources. With a growing number of resources this became a bottleneck.

To solve this we have introduced a new navigation system that introduces new benefits:

  • Context aware navigation - the navigation system is aware of the context of the resource itself.
  • Filtered information - Information is only shown which is relevant to the context of the resource itself.
  • Drilldown navigation - you can drill down into your resources to see more information.
  • Better performance as information is now stored in nanostores.
  • Fully customizable navigation system - define your own navigation system for your catalog.
  • Favorited resources - add your favorite resources to your navigation system.

You can read more about the new context aware navigation in the documentation sidebar documentation.

New caching and performance improvements​

In EventCatalog v3 we have introduced a new caching system that will cache the information for your resources.

We also introduced nanostores to the code base, this will help us with performance and caching of information across pages.

Catalogs now have better lighthouse scores (demo has 100/100).

Store business workflows with your services and domains​

In EventCatalog v3 you can now assign flows to your services and domains.

This can help you document business workflows and features that are relevant to your services and domains.

To get started, you can add the flows property to your domain frontmatter.

New homepage for catalogs​

In EventCatalog v3 we have introduced a new homepage for your catalog.

If you want to customize the homepage you can create a /pages/homepage.astro file and add your own content to it.

llms.txt is now enabled by default​

We have enabled llms.txt by default in EventCatalog v3, as this is a common use case for EventCatalog and helps with AI integrations.

What do I need to do?​

Remove the llmsTxt property from your eventcatalog.config.js file (if you have one)

eventcatalog.config.js
module.exports = {
-   llmsTxt: {
-       enabled: true,
-   }
};

If you want to disable llms.txt you can set the enabled property to false.

eventcatalog.config.js
module.exports = {
    llmsTxt: {
        enabled: false,
    }
};

Known issues​

Please check EventCatalog issues on GitHub for any reported issues, or to file an issue yourself.