# Upgrade to EventCatalog v4 Copy as Markdown[View as Markdown](/docs/development/upgrading/v4.md) *** This guide will help you upgrade from v3 to v4 of EventCatalog. EventCatalog v4 introduces systems as a first-class resource, adds system context maps, updates the Discover and Application sidebar experience, moves EventCatalog onto Astro 7 internally, and removes the PDF export feature. v4 beta The v4 branch is currently published as a beta. If v4 has not been promoted to `latest` yet, install the beta package instead of `latest`. ## Upgrade EventCatalog[​](#upgrade-eventcatalog "Direct link to Upgrade EventCatalog") Update your project's version of EventCatalog using your package manager: ``` npm install @eventcatalog/core@latest ``` If you are testing the v4 beta, use the beta tag: ``` npm install @eventcatalog/core@beta ``` *Problems upgrading? [Try resetting your project](/docs/development/upgrading.md#having-problems).* ## Before you upgrade[​](#before-you-upgrade "Direct link to Before you upgrade") Most v3 catalogs should continue to build without changing their existing resources. You do not need to move your services, messages, flows, entities, or data stores into systems to upgrade to v4. Before upgrading, we recommend: 1. Create a branch for the upgrade. 2. Upgrade `@eventcatalog/core`. 3. Remove `.eventcatalog-core`, `node_modules`, and your lock file if the catalog does not pick up the new version. 4. Run your catalog locally and check custom pages, custom navigation, and visualiser links. ## 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: Export to PDF[​](#removed-export-to-pdf "Direct link to Removed: Export to PDF") The Export to PDF / print feature has been removed from EventCatalog v4. #### What do I need to do?[​](#what-do-i-need-to-do "Direct link to What do I need to do?") Remove any user guidance, screenshots, or internal runbooks that tell people to export resource pages to PDF from EventCatalog. Diagram version comparison is still available, and is no longer gated behind the Scale plan. ### Removed: `/visualiser/context-map`[​](#removed-visualisercontext-map "Direct link to removed-visualisercontext-map") The old global context map route has been removed. #### What do I need to do?[​](#what-do-i-need-to-do-1 "Direct link to What do I need to do?") If you have custom navigation, docs, or bookmarks that link to `/visualiser/context-map`, update them to the new system context map route: eventcatalog.config.js ``` export default { navigation: { pages: [ { type: 'item', title: 'System Context Map', - href: '/visualiser/context-map', + href: '/visualiser/system-context-map', }, ], }, }; ``` ## Breaking changes[​](#breaking-changes "Direct link to Breaking changes") The following changes are considered breaking changes in EventCatalog v4. Breaking changes may or may not affect your catalog depending on how much you customize EventCatalog. ### Changed: EventCatalog now uses Astro 7 internally[​](#changed-eventcatalog-now-uses-astro-7-internally "Direct link to Changed: EventCatalog now uses Astro 7 internally") EventCatalog v4 upgrades the internal application from Astro 6 to Astro 7. Most catalogs do not need to change anything. If you have custom Astro pages, custom integrations, or custom MDX/Markdown processing that depends on Astro internals, review those customizations during the upgrade. #### What do I need to do?[​](#what-do-i-need-to-do-2 "Direct link to What do I need to do?") If your catalog only uses EventCatalog resources and MDX content, upgrade EventCatalog and test the catalog. If you maintain custom Astro pages or custom integrations, check them against Astro 7 behavior and run the catalog locally after upgrading. ### Changed: Application sidebar configuration has moved to `navigation.groups`[​](#changed-application-sidebar-configuration-has-moved-to-navigationgroups "Direct link to changed-application-sidebar-configuration-has-moved-to-navigationgroups") EventCatalog v4 removes the top-level `sidebar` configuration that only let you show or hide items in the Application sidebar. You can now configure the whole Application sidebar using `navigation.groups`. This lets you define groups, labels, item order, icons, custom links, bottom-positioned groups, active route matching, and visibility. info `navigation.pages` still controls the context-aware documentation sidebar. Use `navigation.groups` for the Application sidebar. #### What do I need to do?[​](#what-do-i-need-to-do-3 "Direct link to What do I need to do?") If you are not using the top-level `sidebar` property in `eventcatalog.config.js`, there is nothing to change. If you are using `sidebar`, move that configuration to `navigation.groups`. eventcatalog.config.js ``` export default { - sidebar: [ - { id: '/directory/teams', visible: false }, - { id: '/schemas/fields', visible: false }, - ], + navigation: { + groups: [ + { + id: 'main', + items: [{ id: 'home' }, { id: 'docs' }], + }, + { + id: 'browse', + label: 'Browse', + items: [ + { id: 'catalog' }, + { id: 'schemas' }, + { id: 'schema-insights', visible: false }, + ], + }, + { + id: 'organization', + label: 'Organization', + items: [{ id: 'teams', visible: false }, { id: 'users' }], + }, + { + id: 'settings', + position: 'bottom', + items: [{ id: 'settings' }], + }, + ], + }, }; ``` Built-in Application sidebar item IDs include: * `home` * `docs` * `catalog` * `schemas` * `schema-insights` * `teams` * `users` * `settings` You can also use route IDs such as `/schemas/explorer` or add custom items: eventcatalog.config.js ``` export default { navigation: { groups: [ { id: 'platform', label: 'Platform', items: [ { id: 'platform-docs', label: 'Platform Docs', icon: 'BookOpen', href: '/docs/custom/platform/overview', match: ['/docs/custom/platform'], }, { id: 'support', label: 'Support', icon: 'LifeBuoy', href: 'https://support.example.com', }, ], }, ], }, }; ``` When `navigation.groups` is provided, it replaces the default Application sidebar groups. Add every item you want users to see. If you import `SideBarConfig` from EventCatalog types, remove that import. It is no longer exported. ### Changed: Discover navigation has been simplified[​](#changed-discover-navigation-has-been-simplified "Direct link to Changed: Discover navigation has been simplified") EventCatalog v4 replaces the resource-specific Browse sidebar links with a single Discover experience and a Kind filter. Users can switch between domains, systems, services, messages, flows, entities, data stores, and other resource collections from the Discover page. ![Discover domains page showing the new Kind filter](/assets/images/discover-domains-b50271b85b6157afbb902909d9204964.png) #### What do I need to do?[​](#what-do-i-need-to-do-4 "Direct link to What do I need to do?") If you use the default Application sidebar, there is nothing to change. If you have custom screenshots, onboarding docs, or training material that mentions the old resource-specific Browse links, update them to reference Discover and the Kind filter. ### Changed: System context maps are now the high-level architecture view[​](#changed-system-context-maps-are-now-the-high-level-architecture-view "Direct link to Changed: System context maps are now the high-level architecture view") EventCatalog v4 adds dedicated system context map routes: * `/visualiser/system-context-map` for the global system context map. * `/visualiser/systems/:id/:version/context` for a single system in context. * `/visualiser/domains/:id/:version/systems-context` for systems inside a domain. The existing resource visualiser routes still work for resources such as services and domains. #### What do I need to do?[​](#what-do-i-need-to-do-5 "Direct link to What do I need to do?") Update any custom links that should point users to the new high-level system context map. ## New features[​](#new-features "Direct link to New features") The following new features and improvements have been added to EventCatalog v4. ### Systems are now a first-class resource[​](#systems-are-now-a-first-class-resource "Direct link to Systems are now a first-class resource") Systems are collections of resources that work together to perform a function, such as checkout, payment processing, customer identity, or product search. A system can group the resources that cooperate to deliver one capability, including [services](/docs/development/guides/resources/services/introduction.md), [flows](/docs/development/guides/resources/flows/introduction.md), [entities](/docs/development/guides/resources/entities/introduction.md), [data stores](/docs/development/guides/resources/data/introduction.md), [diagrams](/docs/development/bring-your-own-documentation/diagrams/introduction.md), and documentation. ![Catalog domain system context map showing systems and actors](/assets/images/catalog-systems-context-ab6aa74d2a872ccf06a61fb96fe889ed.png) Systems are versioned resources. You can define them at the top level of your catalog, or inside a domain when that system clearly belongs to a business boundary. * domains / * Payments / * index.mdx * systems / * payment-processing-system / * index.mdx * services / * PaymentAPI / * index.mdx Example system frontmatter: domains/Payments/systems/payment-processing-system/index.mdx ``` --- id: payment-processing-system name: Payment Processing System version: 1.0.0 summary: Handles payment authorization, capture, and refund processing. owners: - payments-platform services: - id: PaymentAPI flows: - id: CheckoutSaga relationships: - id: fraud-detection version: 1.0.0 label: requests fraud checks from --- ``` You can also reference systems from a domain: domains/Payments/index.mdx ``` --- id: payments name: Payments version: 1.0.0 systems: - id: payment-processing-system version: 1.0.0 --- ``` Read more in the [systems documentation](/docs/development/guides/systems/introduction.md). ### System context maps[​](#system-context-maps "Direct link to System context maps") Systems can declare relationships to other systems. EventCatalog uses those relationships to render context maps that show how systems relate to each other. System context maps help users move from a high-level architecture view into a detailed system view. From the global map, users can click into a system, then explore the [services](/docs/development/guides/resources/services/introduction.md), [APIs](/docs/development/guides/resources/schemas/add-specifications-to-services/add-openapi-specifications.md), [messages](/docs/development/guides/resources/messages/what-are-messages.md), [flows](/docs/development/guides/resources/flows/introduction.md), [entities](/docs/development/guides/resources/entities/introduction.md), and [data stores](/docs/development/guides/resources/data/introduction.md) that make up that system. Read more in the [system context maps documentation](/docs/development/guides/systems/system-context-maps.md). ### Systems in the SDK[​](#systems-in-the-sdk "Direct link to Systems in the SDK") The EventCatalog SDK now supports systems. You can read and write systems, add resources to a system, write resources directly into a system, and add systems to domains. This is useful for generators and integrations that sync architecture information from source code, specifications, schema registries, or internal platforms. ### Systems in AI, MCP, and catalog tools[​](#systems-in-ai-mcp-and-catalog-tools "Direct link to Systems in AI, MCP, and catalog tools") EventCatalog Assistant, MCP tools, and catalog tools now understand systems. AI workflows can retrieve systems, inspect system resources, and generate architecture diagrams for systems. ### Systems in Discover, sidebars, teams, and ADRs[​](#systems-in-discover-sidebars-teams-and-adrs "Direct link to Systems in Discover, sidebars, teams, and ADRs") Systems are now available across the catalog experience: * Systems can be discovered on `/discover/systems`. * Systems appear in sidebars with their own icon and color. * Teams and users can own systems. * ADRs can target systems with `appliesTo: [{ type: 'system' }]`. * Resource-level documentation can be attached to systems. ### Top-level diagrams sidebar group[​](#top-level-diagrams-sidebar-group "Direct link to Top-level diagrams sidebar group") EventCatalog v4 adds a Top level diagrams navigation group when systems exist. This surfaces the System Context Map from the sidebar so users can start from the highest-level architecture view. ### Custom homepages are available in Community Edition[​](#custom-homepages-are-available-in-community-edition "Direct link to Custom homepages are available in Community Edition") Custom homepages are now available in Community Edition. You no longer need a paid feature flag to customize the catalog homepage. Create your custom homepage at `pages/homepage.astro`. * pages / * ![](/img/integrations/astro.svg)homepage.astro Custom homepages can also embed the new System Context Map using the `SystemContextMap` component. ## 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.