---
sidebar_position: 2
keywords:
- Upgrade EventCatalog
sidebar_label: v3
title: Upgrade to EventCatalog v3
description: How to upgrade to EventCatalog v3.
---

This guide will help you upgrade from v2 to v3 of EventCatalog. (Missed the announcement? [Read the blog post](/blog/eventcatalog-v3) 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

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

```bash
npm install @eventcatalog/core@latest
```

_Problems upgrading? [Try resetting your project](/docs/development/upgrading#having-problems)._

## 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](/docs/development/ask-your-architecture/eventcatalog-assistant/what-is-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.

```bash
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.

```diff title="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.

### 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

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

#### What do I need to do?

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

```bash
npm uninstall @eventcatalog/generator-ai
```

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

```diff title="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).

### 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)

```bash
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)](https://github.com/event-catalog/eventcatalog/issues/1816)

### 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.

```diff title="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.

```bash
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:

```diff title="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](/docs/development/customization/customize-sidebars/documentation-sidebar).

### 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)

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

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

```diff title="eventcatalog.config.js"
module.exports = {
    llmsTxt: {
        enabled: false,
    }
};
```

## 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.

