# Upgrade to EventCatalog v5 Copy as Markdown[View as Markdown](/docs/development/upgrading/v5.md) *** This guide will help you upgrade from v4 to v5 of EventCatalog. (Missed the announcement? [Read the blog post](/blog/eventcatalog-v5.md) to find out what's changing.) EventCatalog v5 includes every feature in one product, moves the core to the Business Source License 1.1, and brings new visualiser diagrams with levels, flow grouping, Resources pages for more resources, and interactive diagrams in MCP clients. ## Upgrade EventCatalog[​](#upgrade-eventcatalog "Direct link to Upgrade EventCatalog") Install v5 from a clean install v5 uses React 19. If you upgrade over an existing v4 install, your package manager can keep React 18 at the top of `node_modules` and give `@eventcatalog/core` its own copy of React 19. The build then fails with errors such as `Cannot read properties of null (reading 'useState')`. Delete your installed packages and lock file before you install v5. 1. Create a branch for the upgrade. 2. Delete `node_modules`, `.astro` and `.eventcatalog-core` (if you have one). 3. Delete your lock file: `package-lock.json`, `yarn.lock` or `pnpm-lock.yaml`. 4. If your `package.json` lists `react` or `react-dom`, change them to `^19.2.0`. 5. Install v5: ``` rm -rf node_modules .astro .eventcatalog-core package-lock.json npm install @eventcatalog/core@latest ``` If you use yarn or pnpm, delete `yarn.lock` or `pnpm-lock.yaml` instead of `package-lock.json`, and install with that package manager. *Problems upgrading? [Try resetting your project](/docs/development/upgrading.md#having-problems).* ## After you upgrade[​](#after-you-upgrade "Direct link to After you upgrade") Most v4 catalogs build on v5 without changes to their resources. The changes most likely to affect you are flow step validation, `pages/api` routes in static builds, custom React components, and links to visualiser pages. 1. Run `eventcatalog build` and fix any flow step errors it reports. 2. Run your catalog locally and check custom pages, custom components, custom navigation, and links to visualiser pages. ### The license has changed[​](#the-license-has-changed "Direct link to The license has changed") `@eventcatalog/core` 5.0.0 and later is licensed under the Business Source License 1.1 (`BUSL-1.1`). Releases up to and including 4.x stay under the MIT License. Ecosystem packages, such as `@eventcatalog/create-eventcatalog`, stay MIT. The generators, integrations and plugins we publish are MIT too, and no longer need a license key. You can remove `EVENTCATALOG_LICENSE_KEY_*` variables and `licenseKey` options; they are ignored. Read the [licensing FAQ](/license-faq.md) to find out whether you need a commercial license, and [pricing](/pricing.md) for prices. The [blog post](/blog/eventcatalog-v5.md) explains why the license changed. If you have a license, add your `license.jwt` file to the catalog. See [License file](/docs/development/license/license-file.md). ### Every feature is included[​](#every-feature-is-included "Direct link to Every feature is included") Every feature now works without `EVENTCATALOG_SCALE_LICENSE_KEY`, a Starter or Scale plan, or a Backstage license key. This includes custom documentation, resource docs, custom pages, custom styles, the schema API and `schemas.txt`, Fields Explorer lineage, schema diffs, schema and directory sources, private remote files, analytics integrations, embedding, federation, the assistant, the MCP server, authentication and governance checks. Federation is free for organizations that qualify for Free Use. Commercial customers need the Enterprise plan to use federation in production. The [EventCatalog Assistant](/docs/development/ask-your-architecture/eventcatalog-assistant/what-is-eventcatalog-assistant.md), the [MCP server](/docs/development/ask-your-architecture/mcp-server/introduction.md) and [authentication](/docs/development/authentication/introduction.md) still need server output (`output: 'server'`) and their configuration files. #### What do I need to do?[​](#what-do-i-need-to-do "Direct link to What do I need to do?") Nothing. You can remove `EVENTCATALOG_SCALE_LICENSE_KEY` and `EVENTCATALOG_STARTER_LICENSE_KEY` from your environment once you have a `license.jwt`. If you keep them, EventCatalog still recognizes them. ## Removed[​](#removed "Direct link to Removed") The following features have now been entirely removed from the code base and can no longer be used. ### Removed: Billing settings page[​](#removed-billing-settings-page "Direct link to Removed: Billing settings page") The billing settings page (`/settings/billing`) and the upgrade prompts are removed. Your license is shown on the new **Settings > License** page. #### What do I need to do?[​](#what-do-i-need-to-do-1 "Direct link to What do I need to do?") Update any links to `/settings/billing` to `/settings/license`. ### Removed: Domain Integration Map[​](#removed-domain-integration-map "Direct link to Removed: Domain Integration Map") The Domain Integration Map page (`/visualiser/domain-integrations`) is removed. Level 1 of a domain's Diagram shows how domains integrate. #### What do I need to do?[​](#what-do-i-need-to-do-2 "Direct link to What do I need to do?") Update any custom navigation or links that point to `/visualiser/domain-integrations`. ### Removed: Data Dependency Graph[​](#removed-data-dependency-graph "Direct link to Removed: Data Dependency Graph") The service Data Dependency Graph (`/visualiser/services/:id/:version/data`) is removed, along with its sidebar link. Level 2 of the service's Diagram shows the same data stores and the services it talks to. The old route redirects there. #### What do I need to do?[​](#what-do-i-need-to-do-3 "Direct link to What do I need to do?") Nothing. Links redirect. If you embed this page, see [Changed: visualiser routes and levels](#changed-visualiser-routes-and-levels). ### Removed: Separate Resource, Context and System Diagram pages[​](#removed-separate-resource-context-and-system-diagram-pages "Direct link to Removed: Separate Resource, Context and System Diagram pages") Domains and systems now have a single **Diagram** page with three levels. The domain System Diagram (`/visualiser/domains/:id/:version/systems-context`) and the system Context Diagram (`/visualiser/systems/:id/:version/context`) redirect to level 1 of the Diagram page. The old Resource Diagram pages are replaced by the Diagram page. #### What do I need to do?[​](#what-do-i-need-to-do-4 "Direct link to What do I need to do?") Nothing. Links redirect. See [Changed: visualiser routes and levels](#changed-visualiser-routes-and-levels). ### Removed: Architecture overview pages[​](#removed-architecture-overview-pages "Direct link to Removed: Architecture overview pages") The architecture overview pages (`/architecture/{type}/{id}/{version}`) for domains, systems and services are replaced by their Resources pages. Old links redirect to the Resources page, or to the docs page when there is nothing to list. The sidebar's Architecture section no longer has an **Overview** link. #### What do I need to do?[​](#what-do-i-need-to-do-5 "Direct link to What do I need to do?") Nothing. Links redirect. Update custom navigation to point to `/docs/{type}/{id}/{version}/resources`. ### Removed: "Open in EventCatalog Studio" menu item[​](#removed-open-in-eventcatalog-studio-menu-item "Direct link to Removed: \"Open in EventCatalog Studio\" menu item") The visualiser canvas menu no longer has the **Open in EventCatalog Studio** item. #### What do I need to do?[​](#what-do-i-need-to-do-6 "Direct link to What do I need to do?") Remove any internal guidance that tells people to use this menu item. ### Removed: `EVENTCATALOG_SHOW_BRANDING`[​](#removed-eventcatalog_show_branding "Direct link to removed-eventcatalog_show_branding") The EventCatalog branding (the Discord and GitHub links in the header and the footer) is always shown. `EVENTCATALOG_SHOW_BRANDING` is no longer used. #### What do I need to do?[​](#what-do-i-need-to-do-7 "Direct link to What do I need to do?") Remove `EVENTCATALOG_SHOW_BRANDING` from your environment. ### Removed: `ENABLE_EMBED`[​](#removed-enable_embed "Direct link to removed-enable_embed") In v4, the EventCatalog CLI set `ENABLE_EMBED` from your license. `ENABLE_EMBED`, `EVENTCATALOG_STARTER` and `EVENTCATALOG_SCALE` are no longer passed to the Astro runtime. Embedding works for every catalog: add `embed=true` to a URL. See [Embed EventCatalog](/docs/development/customization/embed-eventcatalog.md). #### What do I need to do?[​](#what-do-i-need-to-do-8 "Direct link to What do I need to do?") Nothing, unless your custom code uses them. If it reads `ENABLE_EMBED`, `EVENTCATALOG_STARTER` or `EVENTCATALOG_SCALE`, or imports `isEventCatalogStarterEnabled` or `isEventCatalogScaleEnabled` from `@utils/feature`, remove those checks. ## Breaking changes[​](#breaking-changes "Direct link to Breaking changes") The following changes are considered breaking changes in EventCatalog v5. Breaking changes may or may not affect your catalog depending on how much you customize EventCatalog. ### Changed: visualiser routes and levels[​](#changed-visualiser-routes-and-levels "Direct link to Changed: visualiser routes and levels") Every diagram now has the same three levels, shown as L1, L2 and L3 in the canvas toolbar: | Level | `?level=` | Shows | | ----- | --------- | ---------------------------------------- | | L1 | `1` | Domains, systems and their relationships | | L2 | `2` | Services and data stores | | L3 | `3` | Adds messages and channels | Domain and system diagrams live at `/visualiser/domains/:id/:version` and `/visualiser/systems/:id/:version`. Old routes redirect: | Old route | Redirects to | | -------------------------------------------------- | ------------------------------------------- | | `/visualiser/domains/:id/:version/systems-context` | `/visualiser/domains/:id/:version?level=1` | | `/visualiser/systems/:id/:version/context` | `/visualiser/systems/:id/:version?level=1` | | `/visualiser/services/:id/:version/data` | `/visualiser/services/:id/:version?level=2` | #### What do I need to do?[​](#what-do-i-need-to-do-9 "Direct link to What do I need to do?") * If you link to a diagram with `?level=`, check the value matches the new levels. * Update embedded URLs that use the old routes. The redirect drops the query string, including `embed=true`. * Update custom navigation that points to the old routes. ### Changed: sidebar labels[​](#changed-sidebar-labels "Direct link to Changed: sidebar labels") Sidebar links have been renamed: | v4 label | v5 label | | -------------------------------------- | ---------------------- | | System Diagram (domains) | Diagram | | Resource Diagram (domains and systems) | Diagram | | Context Diagram (systems) | Diagram | | Map | Diagram | | Entity Map | Entity Diagram | | System Context Map | System Context Diagram | | Domain Resources | Resources | | System Resources | Resources | | Data Dependency Graph | Removed | | Overview (in the Architecture section) | Removed | Entity diagram pages and custom docs domain embeds also say "Diagram" instead of "Map". #### What do I need to do?[​](#what-do-i-need-to-do-10 "Direct link to What do I need to do?") Update screenshots, onboarding docs and training material that use the old labels. ### Changed: saved layouts for old Resource Diagrams don't carry over[​](#changed-saved-layouts-for-old-resource-diagrams-dont-carry-over "Direct link to Changed: saved layouts for old Resource Diagrams don't carry over") Diagrams are now laid out with ELK instead of dagre, and domains and systems are laid out inside their boxes. Layouts you saved in dev mode for a domain's or system's old Resource Diagram don't carry over to the new Diagram page. Layouts saved for a system's context diagram carry over to level 1. #### What do I need to do?[​](#what-do-i-need-to-do-11 "Direct link to What do I need to do?") Open the diagram in `eventcatalog dev` and save the layout again if needed. ### Changed: `pages/api` routes require `output: 'server'`[​](#changed-pagesapi-routes-require-output-server "Direct link to changed-pagesapi-routes-require-output-server") Custom pages are now served for every catalog. In v4, catalogs without a Scale license skipped them. A `pages/api` directory now requires server output: a static build fails with a message instead of skipping the routes. #### What do I need to do?[​](#what-do-i-need-to-do-12 "Direct link to What do I need to do?") If you have a `pages/api` directory, set `output: 'server'` in `eventcatalog.config.js`, or remove the directory. eventcatalog.config.js ``` export default { output: 'server', }; ``` See the [custom pages and API routes reference](/docs/development/customization/custom-pages-and-api-routes/reference.md). ### Changed: custom React components run on React 19[​](#changed-custom-react-components-run-on-react-19 "Direct link to Changed: custom React components run on React 19") EventCatalog now uses React and React DOM 19. React components in your catalog's `components/` folder run on React 19. #### What do I need to do?[​](#what-do-i-need-to-do-13 "Direct link to What do I need to do?") If your `package.json` lists `react` or `react-dom`, change them to `^19.2.0` and reinstall from a clean install, as in [Upgrade EventCatalog](#upgrade-eventcatalog). If any of your components use APIs that React 19 removed, update them: * `defaultProps` on function components * `propTypes` * string refs * `ReactDOM.render` * `findDOMNode` See the [custom components reference](/docs/development/components/custom-components/reference.md#react-components). ### Changed: header shows `repositoryUrl` next to the EventCatalog links[​](#changed-header-shows-repositoryurl-next-to-the-eventcatalog-links "Direct link to changed-header-shows-repositoryurl-next-to-the-eventcatalog-links") When [`repositoryUrl`](/docs/api/config.md#repositoryUrl) is set, the header shows your repository link next to the EventCatalog Discord and GitHub links, rather than in place of them. #### What do I need to do?[​](#what-do-i-need-to-do-14 "Direct link to What do I need to do?") Nothing. ### Changed: flow steps are validated[​](#changed-flow-steps-are-validated "Direct link to Changed: flow steps are validated") Mistakes in flows no longer fail silently: * Unknown step properties fail the build. Custom properties must start with `x-`. * Steps that use two node types, or both `next_step` and `next_steps`, fail with a message naming the step and what to change. * A `next_step` to a step that doesn't exist, or a reference to a resource that isn't in the catalog, logs a warning naming the flow and the step. * The step `type` field is still accepted, but ignored. The [EventCatalog Linter](/docs/development/developer-tools/eventcatalog-linter.md) checks the same rules, and adds `refs/flow-step-exists` for next steps that aren't in the flow. #### What do I need to do?[​](#what-do-i-need-to-do-15 "Direct link to What do I need to do?") Run `eventcatalog build` and fix any errors. Rename custom step properties to start with `x-`: flows/Checkout/index.mdx ``` steps: - id: place-order title: Place order service: id: OrderService - priority: high + x-priority: high ``` ### Changed: `@eventcatalog/visualiser` API[​](#changed-eventcatalogvisualiser-api "Direct link to changed-eventcatalogvisualiser-api") This only affects you if you use the `@eventcatalog/visualiser` package directly, for example to embed the visualiser in your own application. * `layoutGraph` now returns a promise. * The dagre helpers (`createDagreGraph`, `layoutDagreGraph`, `getNodesAndEdgesFromDagre`, `calculatedNodes`) are removed. * Edges are drawn along the route in `data.route` when there is one. * A new `@eventcatalog/visualiser/layout` entry (no React) exports `layoutWithElk`, `getNodeSize`, `hideMessageNodes`, `hideNodes`, `getMessagesLabel`, `isCarrier` and `isMessageNode`. #### What do I need to do?[​](#what-do-i-need-to-do-16 "Direct link to What do I need to do?") `await` calls to `layoutGraph`, and replace the dagre helpers with `layoutWithElk` from `@eventcatalog/visualiser/layout`. ## New features[​](#new-features "Direct link to New features") The following new features and improvements have been added to EventCatalog v5. ### Diagram levels and the canvas toolbar[​](#diagram-levels-and-the-canvas-toolbar "Direct link to Diagram levels and the canvas toolbar") Every diagram has a floating canvas toolbar with the levels (L1, L2, L3), simulate messages, the minimap and fit to view. Levels a diagram doesn't have are greyed out. The level is kept in the URL, so shared links open at the same level. Clicking a legend entry now hides or shows those nodes. The canvas menu has a **Hide messages** option. ### Domain and system Diagram pages[​](#domain-and-system-diagram-pages "Direct link to Domain and system Diagram pages") A domain's Diagram shows the domain with its systems and the other domains they send messages to or receive them from (L1). L2 expands the systems into their services and data stores, and L3 adds messages and channels. Subdomains are shown as domains inside the domain. ![Payments domain diagram at level 1](/assets/images/domain-diagram-l1-1277bd6e182cf3fc070a1a3bdca48f29.png) ![Payments domain diagram at level 2](/assets/images/domain-diagram-l2-f0d0ee018c82f7cde9ff6a3f9dad5de6.png) On a domain's diagram, the toolbar has **Highlight cross-domain communication**, which picks out the edges to and from other domains. A system's Diagram shows the system context at L1, expands the system into its services at L2, and adds messages and channels at L3. Read more in [System diagrams](/docs/development/guides/systems/system-context-maps.md). ### Group flows by domain, system or team[​](#group-flows-by-domain-system-or-team "Direct link to Group flows by domain, system or team") Flows can group their steps by domain, system, team, or domain then system, drawn as boxes or lanes. Use the **Group by** menu (top right, or press G). Groups come from the catalog, so your flows need no changes. The choice is kept in the URL (`?group=system&groupStyle=boxes`). ![Flow grouped by system with the Group by menu open](/assets/images/flow-group-by-da8d9720dc6e409db357996aad9b3dbb.png) To start a flow grouped in your docs, use ``. See the [Flow component](/docs/development/components/components/flow.md). Flows no longer show the L1/L2/L3 levels. The step-by-step walkthrough is smaller and starts at the first step: it numbers the steps walked so far, rings the current step, and offers a dropdown at branches. ### Channel flow steps[​](#channel-flow-steps "Direct link to Channel flow steps") Flow steps can reference channels with `channel: { id, version }`. A step's `title` is now optional and defaults to the name of what it references. The SDK adds `FlowBuilder.addChannelStep`. flows/Checkout/index.mdx ``` steps: - id: orders-topic channel: id: orders version: 1.0.0 next_step: notify-customer ``` Read more in the [flows documentation](/docs/development/guides/resources/flows/introduction.md). ### Resources pages for services, flows, channels and messages[​](#resources-pages-for-services-flows-channels-and-messages "Direct link to Resources pages for services, flows, channels and messages") Services, flows, channels, events, commands and queries now have a Resources page, like domains and systems, linked from Quick Reference in the sidebar. Every Resources page lists the decision records (ADRs) that apply to it, and has a Relationship column (for example Sends, Receives, Reads from, Writes to) with Inbound and Outbound filters. ![Order Service Resources page with Inbound and Outbound filters](/assets/images/service-resources-page-121eae4e91f954cfabf74ac664f3c36d.png) Read more about the [service Resources page](/docs/development/guides/resources/services/resources-page.md), the [message Resources page](/docs/development/guides/resources/messages/what-are-messages.md#resources-page) and the [channel Resources page](/docs/development/guides/resources/messages/message-channels/introduction.md#resources-page). ### Interactive diagrams and schemas in MCP clients[​](#interactive-diagrams-and-schemas-in-mcp-clients "Direct link to Interactive diagrams and schemas in MCP clients") The MCP server has a new `showResource` tool. With `view: "architecture"` it returns a resource's diagram, built the same way as its Diagram page. With `view: "schema"` it shows a message's schema. In MCP clients that support MCP Apps (for example Claude, ChatGPT and VS Code) these open as interactive views. Other clients get Mermaid or the schema code. Every MCP tool now has a title and is read-only, versions are optional, and hidden resources are not listed. Read more in [interactive diagrams and schemas](/docs/development/ask-your-architecture/mcp-server/getting-started.md#interactive-diagrams-and-schemas). ### Settings > MCP lists domain MCP servers[​](#settings--mcp-lists-domain-mcp-servers "Direct link to Settings > MCP lists domain MCP servers") **Settings > MCP** lists each domain's MCP server next to the Catalog MCP Server, with full URLs to copy. See the [MCP server documentation](/docs/development/ask-your-architecture/mcp-server/introduction.md). ### License status in the CLI and Settings > License[​](#license-status-in-the-cli-and-settings--license "Direct link to License status in the CLI and Settings > License") `eventcatalog dev` and `eventcatalog build` show the catalog's license or trial in the terminal. While you run `eventcatalog dev`, the header shows the trial, or a reminder when your license is about to expire. The new **Settings > License** page shows who the catalog is licensed to and when the license expires. Read more in [License file](/docs/development/license/license-file.md). ## 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.