# Upgrade to EventCatalog v3

Copy as Markdown[View as Markdown](/docs/development/upgrading/v3.md)

***

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

Need to see the v2 docs? Visit this [older version of the docs site](https://v2.eventcatalog.dev/). EventCatalog V2 will continue to get security updates, but new features and improvements will only be available in v3.

## Upgrade EventCatalog[​](#upgrade-eventcatalog "Direct link to 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](/docs/development/upgrading.md#having-problems).*

## Deprecated[​](#deprecated "Direct link to 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[​](#deprecated-visualizer-sidebar-icon "Direct link to 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[​](#deprecated-architecture-pages "Direct link to 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[​](#deprecated-resource-sidebars "Direct link to 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[​](#deprecated-eventcataloggenerator-ai-package "Direct link to deprecated-eventcataloggenerator-ai-package")

The AI package has been removed and replaced with the [EventCatalog Assistant](/docs/development/ask-your-architecture/eventcatalog-assistant/what-is-eventcatalog-assistant.md).

#### What do I need to do?[​](#what-do-i-need-to-do "Direct link to 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[​](#removed "Direct link to 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[​](#removed-list_view-and-side_view-navigation-options "Direct link to 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?[​](#what-do-i-need-to-do-1 "Direct link to 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[​](#removed-docs-landing-page "Direct link to 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?[​](#what-do-i-need-to-do-2 "Direct link to 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.

### Removed: Pagefind (updated search)[​](#removed-pagefind-updated-search "Direct link to Removed: Pagefind (updated search)")

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[​](#removed-eventcatalog-chat "Direct link to 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](/docs/development/ask-your-architecture/eventcatalog-assistant/what-is-eventcatalog-assistant.md).

#### What do I need to do?[​](#what-do-i-need-to-do-3 "Direct link to 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](/docs/development/ask-your-architecture/eventcatalog-assistant/what-is-eventcatalog-assistant.md).

### Removed: EventCatalog Chat prompts[​](#removed-eventcatalog-chat-prompts "Direct link to Removed: EventCatalog Chat prompts")

We have removed the EventCatalog Chat prompts in EventCatalog.

#### What do I need to do?[​](#what-do-i-need-to-do-4 "Direct link to 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[​](#removed-governance-reports "Direct link to 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[​](#breaking-changes "Direct link to 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[​](#changed-domain-hierarchy-changed "Direct link to 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)](https://github.com/event-catalog/eventcatalog/issues/1816)

### Changed: Authentication[​](#changed-authentication "Direct link to 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[​](#changed-eventcatalog-no-longer-supports-md-files "Direct link to 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?[​](#what-do-i-need-to-do-5 "Direct link to 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[​](#changed-changelogs-are-disabled-by-default "Direct link to 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?[​](#what-do-i-need-to-do-6 "Direct link to 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[​](#new-features "Direct link to New features")

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

### New context aware navigation[​](#new-context-aware-navigation "Direct link to 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](/docs/development/customization/customize-sidebars/documentation-sidebar.md).

### New caching and performance improvements[​](#new-caching-and-performance-improvements "Direct link to 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[​](#store-business-workflows-with-your-services-and-domains "Direct link to 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[​](#new-homepage-for-catalogs "Direct link to 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[​](#llmstxt-is-now-enabled-by-default "Direct link to 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?[​](#what-do-i-need-to-do-7 "Direct link to 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[​](#known-issues "Direct link to Known issues")

Please check [EventCatalog issues on GitHub](https://github.com/event-catalog/eventcatalog/issues) for any reported issues, or to file an issue yourself.