Introducing EventCatalog v3

It's been over 18 months since EventCatalog v2 was released, and what a journey it's been.

Since then, EventCatalog has grown beyond anything I could have imagined. The community on Discord has now surpassed 1,200 members, we've shipped over 70 releases, introduced countless new features, and watched teams around the world use EventCatalog to bring discoverability and documentation to their architectures.

Today, I'm excited to announce EventCatalog v3.

Why v3?

Over the past 18 months, we've listened carefully to the community. As catalogs grew larger with more domains, services, messages, and resources, we saw common patterns emerge around navigation, performance, and customization.

EventCatalog v3 is our response to these challenges. We've worked hard to minimize breaking changes while delivering meaningful improvements to how teams discover and navigate their architecture documentation.

This release focuses on three key areas:

1. Navigation: A completely redesigned navigation system that scales with your architecture
2. Performance: New caching and state management for faster load times
3. Simplicity: Streamlined AI integrations and a cleaner, more focused experience

What's new in EventCatalog v3

New context-aware navigation

The most significant change in v3 is the completely redesigned navigation system.

View the demo

In v2, the sidebar navigation worked well for smaller catalogs but became increasingly difficult to manage as organizations scaled. Teams with hundreds of resources found themselves scrolling endlessly or struggling to find what they needed.

The new context-aware navigation solves this by:

• Showing relevant information: Navigation adapts based on the resource you're viewing
• Enabling drilldown exploration: Navigate through your architecture naturally, drilling down into domains, services, and messages
• Supporting favorites: Pin frequently accessed resources for quick access
• Being fully customizable: Define your own navigation structure that fits your team's needs

This change means the old LIST_VIEW and SIDE_VIEW sidebar options have been removed. The new system is more flexible and powerful than both combined.

You can read more in the documentation sidebar guide.

Performance improvements

EventCatalog v3 introduces a new caching system and adopts nanostores for state management across pages.

What does this mean for you?

• Faster page loads and navigation
• Search no longer requires a full build, it works instantly
• The demo catalog now scores 100/100 on Lighthouse

These improvements are especially noticeable on larger catalogs where the previous architecture could become sluggish.

New search experience

We've replaced Pagefind with a new search implementation powered by nanostores.

The old approach required running search indexing after every build. Now, search just works. No additional build steps, no waiting, just instant results as you type.

Simplified AI with EventCatalog Assistant

We've retired EventCatalog Chat and the @eventcatalog/generator-ai package in favor of the new EventCatalog Assistant.

View the documentation

The new approach is simpler and more powerful:

• Bring any AI model you want: OpenAI, Anthropic, local models, and more
• Control over the tools you want to use
• Single configuration file for AI settings
• Context aware conversations with your resources
• More natural conversation flow with your architecture

If you were using the old chat feature, migration is straightforward. Just remove the old package and follow the AI Assistant setup guide.

Store business workflows with services and domains

A highly requested feature: you can now assign flows to your services and domains.

This allows you to document business workflows, user journeys, and feature flows alongside your technical architecture. It bridges the gap between business and technical documentation.

domains/Orders/index.mdx

---
id: Orders
flows:
  - id: checkout-flow
  - id: refund-flow
---

New homepage

EventCatalog v3 introduces a fresh default homepage for your catalog.

If you want to customize it, you can create a /pages/homepage.astro file with your own content. The old /pages/index.mdx approach has been removed in favor of this more flexible Astro-based customization.

What's changed

Breaking changes

We've worked hard to minimize breaking changes, but a few are necessary for v3:

• Domain hierarchy is now explicit: Domains no longer automatically inherit all resources from subdomains. You now specify exactly what belongs in each domain. Read more.

• Authentication configuration: If you're using authentication, you'll need to add auth.enabled: true to your config. Read more.

• Only MDX files supported: EventCatalog no longer supports .md files. Run eventcatalog convert to convert any remaining markdown files.

What's been removed

• The /architecture/ overview pages have been replaced with per-domain and per-service architecture views
• The resource sidebar (right-side panel) is now integrated into the new navigation
• The visualizer sidebar icon (access the visualizer through the new navigation instead)
• EventCatalog Chat prompts (custom prompts will return in a future update)

Upgrading to v3

Upgrading is straightforward for most catalogs:

npm install @eventcatalog/core@latest

We recommend reviewing the full upgrade guide to understand all changes and ensure a smooth transition.

If you're running v2, you can continue to reference the v2 documentation as needed.

Looking ahead

EventCatalog v3 lays the foundation for what's coming next. With the new navigation system and improved performance, we're better positioned to deliver features the community has been asking for:

• Domain-level events and specifications
• Container support in EventCatalog
• Data products
• Webhook support

We're also continuing to improve our integrations with schema registries, API gateways, and developer portals like Backstage.

Thank you

EventCatalog wouldn't be where it is today without the community. Every bug report, feature request, Discord conversation, and GitHub star has helped shape this release.

Complexity in event-driven architectures is inevitable, but it can be managed through effective documentation and discoverability. That vision hasn't changed since v1, and v3 brings us closer to making it a reality for teams of all sizes.

If you like EventCatalog, I would love a star on GitHub, and feel free to join our Discord community of over 1,200 members.

Thank you for being part of this journey. Here's to the next chapter.

---

Ready to get started?

# New catalog
npx @eventcatalog/create-eventcatalog@latest my-catalog

# Upgrade existing catalog
npm install @eventcatalog/core@latest

Read the upgrade guide | View the demo | Join Discord