@eventcatalog/core 3.34.0 → 3.35.1

package/dist/docs/development/upgrading/v3.md

@@ -0,0 +1,277 @@
+---
+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.
+

package/dist/docs/miro/_category_.json

@@ -0,0 +1,12 @@
+{
+  "label": "Miro",
+  "position": 4,
+  "collapsible": false,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "slug": "miro",
+    "title": "EventCatalog Miro App",
+    "description": "Visualize your EventCatalog resources on Miro boards"
+  }
+}

package/dist/docs/miro/contributing/01-getting-involved.md

@@ -0,0 +1,53 @@
+---
+sidebar_position: 1
+sidebar_label: Getting Involved
+title: "Getting Involved"
+description: How to contribute to the EventCatalog Miro App
+slug: /miro/getting-involved
+---
+
+The EventCatalog Miro App is open source and we welcome contributions of all kinds — from bug reports and feature requests to code contributions and documentation improvements.
+
+### Ways to contribute
+
+#### Report bugs and request features
+
+Found a bug or have an idea for a new feature? [Open a GitHub issue](https://github.com/event-catalog/eventcatalog-miro-app/issues) and let us know. Please include as much detail as possible — screenshots, steps to reproduce, and what you expected to happen.
+
+#### Join the community
+
+Our [Discord community](https://eventcatalog.dev/discord) is the best place to ask questions, share feedback, and connect with other users building with EventCatalog. We're active there and happy to help.
+
+#### Contribute code
+
+The app is built with React, TypeScript, and the Miro Web SDK. To get started:
+
+1. Fork the repository: [github.com/event-catalog/eventcatalog-miro-app](https://github.com/event-catalog/eventcatalog-miro-app)
+2. Clone your fork and install dependencies:
+   ```bash
+   git clone https://github.com/<your-username>/eventcatalog-miro-app.git
+   cd eventcatalog-miro-app
+   npm install
+   ```
+3. Start the development server:
+   ```bash
+   npm run dev
+   ```
+4. Make your changes and open a pull request
+
+#### Improve the documentation
+
+If you spot something missing or unclear in these docs, contributions are welcome. The documentation lives alongside the main EventCatalog website.
+
+### What we're looking for
+
+The app is in beta and there are plenty of areas where help is appreciated:
+
+- **Bug fixes** — if you find something broken, a fix is always welcome
+- **New features** — check the [issues page](https://github.com/event-catalog/eventcatalog-miro-app/issues) for feature requests or propose your own
+- **Testing** — try the app with your own catalog and let us know how it goes
+- **Feedback** — share what works well and what could be improved
+
+### Code of conduct
+
+Please be kind and respectful in all interactions. We're building this together and every contribution matters.

package/dist/docs/miro/contributing/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Contributing",
+  "position": 5,
+  "collapsible": false,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "title": "Contributing to the Miro App",
+    "description": "Help improve the EventCatalog Miro App"
+  }
+}

package/dist/docs/miro/getting-started/01-overview.md

@@ -0,0 +1,63 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog Miro
+- Miro integration
+- architecture visualization
+sidebar_label: Overview
+title: "EventCatalog Miro App"
+description: Bring your EventCatalog architecture into Miro for collaborative visual design
+slug: /miro/overview
+---
+
+The EventCatalog Miro App lets you bring your architecture artifacts you already documented into Miro — drag services, events, commands, and more onto a board to collaboratively design and explore your systems.
+
+<div style={{textAlign: "center"}}>
+  <img src="/img/miro/getting-started/example.png" alt="Panel" style={{width: "75%"}} />
+  <span style={{display: "block", fontSize: "0.8rem", color: "#6B7280", marginTop: "0.5rem"}}>EventCatalog Miro Application</span>
+</div>
+
+:::info Beta — we'd love your feedback
+The EventCatalog Miro App is currently in beta. We're actively building new features and improving the experience based on real-world usage.
+
+If you run into any issues, have ideas for new features, or want to share how you're using the app, we'd love to hear from you:
+
+- [Join our Discord community](https://eventcatalog.dev/discord) to chat with us and other users
+- [Raise a GitHub issue](https://github.com/event-catalog/eventcatalog-miro-app/issues) to report bugs or request features
+- [Contribute to the project](https://github.com/event-catalog/eventcatalog-miro-app) — the app is open source and contributions are welcome
+:::
+
+### Why use the Miro App?
+
+EventCatalog helps you document your architecture. Many teams already use Miro to help visualize and model new ideas.
+
+The EventCatalog Miro application helps you model and plan what comes next using tools you already use. Model new services, new events, new connections — you need a space to think visually with your team.
+
+The Miro App bridges that gap:
+
+- **Import your real architecture** — bring services, events, commands, queries, channels, and data stores from EventCatalog into Miro
+- **Design collaboratively** — drag resources onto the board, draw connections, and model your next iteration as a team
+- **Create new resources** — sketch out new services and events directly in the app before they exist in code
+- **Stay grounded in reality** — your board is built from real architecture artifacts, not generic boxes and lines
+
+### How it works
+
+1. **Export** your catalog from your EventCatalog project
+2. **Import** the JSON into the Miro App
+3. **Drag** resources onto the board to visualize your architecture
+4. **Design** what comes next — add new resources, draw connections, and collaborate with your team
+
+### Supported resources
+
+| Resource | Description |
+|----------|-------------|
+| **Services** | Microservices and systems in your architecture |
+| **Events** | Domain events flowing between services |
+| **Commands** | Command messages handled by services |
+| **Queries** | Query messages for reading data |
+| **Channels** | Message brokers and routing channels |
+| **Data Stores** | Databases and storage systems |
+
+### Getting in touch
+
+If you have any questions, feedback, or want to get in touch, please join our [Discord community](https://eventcatalog.dev/discord) or [raise a GitHub issue](https://github.com/event-catalog/eventcatalog-miro-app/issues).

package/dist/docs/miro/getting-started/02-installation.md

@@ -0,0 +1,37 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog Miro
+- Miro app install
+sidebar_label: Installation
+title: "Installing the Miro App"
+description: How to install the EventCatalog Miro app to your Miro board
+slug: /miro/installation
+---
+
+### Install the app
+
+1. Open the [EventCatalog Miro App install link](https://miro.com/app-install/?response_type=code&client_id=3458764623600229458&redirect_uri=%2Fapp-install%2Fconfirm%2F)
+2. Select the team and board where you want to install the app
+3. Click **Tools, Media and Integrations**
+4. Search for **EventCatalog** and click on the app.
+
+### Opening the app
+
+Click the **EventCatalog icon** in the toolbar to open the app panel. The panel opens on the right side of your board.
+
+<div style={{textAlign: "center"}}>
+  <img src="/img/miro/getting-started/panel.png" alt="Panel" style={{width: "50%"}} />
+  <span style={{display: "block", fontSize: "0.8rem", color: "#6B7280", marginTop: "0.5rem"}}>The EventCatalog icon in the Miro toolbar</span>
+</div>
+
+:::tip Auto-open on selection
+When you select a node on the board, the app panel will automatically open and show that resource's details — even if the panel was closed.
+:::
+
+### Requirements
+
+- A Miro account (free or paid)
+- An EventCatalog project with resources to import
+
+No authentication or API keys are required. The app runs entirely in your browser and stores data locally.

package/dist/docs/miro/getting-started/03-connecting-to-eventcatalog.md

@@ -0,0 +1,59 @@
+---
+sidebar_position: 3
+keywords:
+- EventCatalog Miro
+- import catalog
+- connect EventCatalog
+sidebar_label: Connecting to EventCatalog
+title: "Connecting to EventCatalog"
+description: Export and import your EventCatalog resources into the Miro app
+slug: /miro/connecting-to-eventcatalog
+---
+
+To use the Miro App, you first need to export your EventCatalog data and import it into the app.
+
+### Step 1: Export your catalog
+
+In your EventCatalog project, run the export command:
+
+```bash
+npm run export
+```
+
+This generates a JSON file containing all your resources — services, events, commands, queries, channels, and data stores — along with their relationships, owners, and metadata.
+
+### Step 2: Import into the Miro App
+
+Open the EventCatalog app in Miro and click **Import Resources**. You have two options:
+
+#### Option A: Upload a file
+
+Click the upload area and select the exported JSON file from your file system.
+
+#### Option B: Paste JSON
+
+Copy the contents of the exported JSON file and paste it into the text area, then click **Import**.
+
+The app validates the JSON before importing. If the format is invalid, you'll see an error message — check that you're using the output from `npm run export`.
+
+### What gets imported?
+
+All resources from your catalog are imported and organized by type:
+
+- **Services** — with their sends, receives, writesTo, and readsFrom relationships
+- **Events, Commands, Queries** — message types with producer/consumer information
+- **Channels** — message brokers with routing configuration
+- **Data Stores** — databases with read/write relationships
+- **Owners and Teams** — used to display ownership on resources
+
+### Re-importing
+
+You can import a new catalog at any time by clicking **Import Resources** from the dashboard. This replaces your current data with the new import.
+
+:::info Data is stored locally
+All imported data is stored in your browser's local storage. No data is sent to any server. If you clear your browser data, you'll need to re-import your catalog.
+:::
+
+### Next steps
+
+Once your data is imported, you're ready to start adding resources to the board. Head to the [guides](/docs/miro/adding-resources) to learn how.

package/dist/docs/miro/getting-started/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Getting Started",
+  "position": 1,
+  "collapsible": false,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "title": "Getting Started with the Miro App",
+    "description": "Install and connect EventCatalog to Miro"
+  }
+}

package/dist/docs/miro/guides/01-adding-resources-to-board.md

@@ -0,0 +1,90 @@
+---
+sidebar_position: 1
+sidebar_label: Adding resources to the board
+title: "Adding Resources to the Board"
+description: Drag and drop services, events, commands, and more onto your Miro board
+slug: /miro/adding-resources
+---
+
+Once you've [imported your catalog](/docs/miro/connecting-to-eventcatalog), you can start adding resources to your Miro board.
+
+### The dashboard
+
+After importing, you'll see the dashboard — a grid showing all your resource categories with the number of resources in each:
+
+- **Services** — microservices and systems
+- **Events** — domain events
+- **Commands** — command messages
+- **Queries** — query messages
+- **Channels** — message brokers and routing
+- **Data Stores** — databases and storage
+
+Click any category to drill into its resource list.
+
+### Dragging resources onto the board
+
+There are two ways to add resources to the board:
+
+#### From the category list
+
+1. Click a category (e.g. **Services**) to see all resources in that category
+2. Grab a resource by its drag handle and drag it onto the Miro board
+3. The resource appears on the board as a card with its name, version, and metadata
+
+Each resource in the list shows its name, version, summary, and owners. You can search to filter resources down.
+
+#### From the dashboard
+
+You can also drag a category card directly from the dashboard onto the board. This creates a new blank resource of that type on the board — useful for quickly sketching out resources that don't exist yet.
+
+<div style={{textAlign: "center"}}>
+  <img src="/img/miro/guides/list-of-services.png" alt="Panel" style={{width: "15%"}} />
+  <span style={{display: "block", fontSize: "0.8rem", color: "#6B7280", marginTop: "0.5rem"}}>Imported Services for Miro</span>
+</div>
+
+
+### Display modes
+
+The app supports two display modes for how resources appear on the board. You can switch between them from the **Display Mode** toggle on the dashboard:
+
+#### App Card
+
+<div style={{textAlign: "center"}}>
+  <img src="/img/miro/guides/app-card.png" alt="Panel" style={{width: "50%"}} />
+  <span style={{display: "block", fontSize: "0.8rem", color: "#6B7280", marginTop: "0rem", marginBottom: "1rem"}}>Style - App Card</span>
+</div>
+
+
+The default mode. Resources appear as Miro App Cards with:
+- Resource name as the title
+- Summary as the description
+- Version, category, owners, and badges as fields
+- Color-coded by resource type
+- Status indicator (Active, Draft, or Deprecated)
+
+#### Post-it
+
+<div style={{textAlign: "center"}}>
+  <img src="/img/miro/guides/post-it.png" alt="Panel" style={{width: "50%"}} />
+  <span style={{display: "block", fontSize: "0.8rem", color: "#6B7280", marginTop: "0rem", marginBottom: "1rem"}}>Style - Post-it</span>
+</div>
+
+Resources appear as colored Miro sticky notes with the resource name. This is a simpler, more compact view — useful when you want a high-level overview without the detail.
+
+:::tip Switching display modes
+When you switch display modes, all existing resources on the board are automatically converted to the new format. Connections between resources are preserved.
+:::
+
+### Auto-layout
+
+If your board gets messy, click the **Auto-layout** button in the dashboard header. This automatically arranges all resources on the board using a left-to-right directed graph layout, organizing connected resources into a clean flow.
+
+### Finding resources on the board
+
+<div style={{textAlign: "center"}}>
+  <img src="/img/miro/guides/focus.png" alt="Panel" style={{width: "50%"}} />
+  <span style={{display: "block", fontSize: "0.8rem", color: "#6B7280", marginTop: "0rem", marginBottom: "1rem"}}>Style - Post-it</span>
+</div>
+
+
+When browsing the resource list, hover over any resource to reveal a crosshair icon. Click it to zoom to that resource on the board — helpful when you have a large board and need to find a specific resource.