@eventcatalog/core 3.35.0 → 3.36.1

package/dist/docs/development/00-why-eventcatalog.md

@@ -0,0 +1,87 @@
+---
+sidebar_position: 1
+slug: /development/getting-started/introduction
+keywords:
+- EventCatalog introduction
+sidebar_label: Why EventCatalog?
+title: Why EventCatalog?
+description: EventCatalog is an open source project to help you bring discoverability to your event-driven architecture.
+---
+
+Many companies adopting event-driven architectures end up in a **distributed big ball of mud**.
+
+There can be many reasons for this...but one overlooked reason is that teams are not documenting their architectures, they lack standards, governance and discoverability.
+
+Your teams start to ask questions like:
+
+- _"What messages do we have?"_
+- _"How are consumers and producers using these messages?"_
+- _"What common fields are across our schemas? What is the drift?"_
+- _"What's the business context behind this architecture?"_
+- _"Where can I find the schemas of these messages?"_
+- _"What services or domains do we have in our architecture?"_
+- _"How can I make changes?"_
+- _"Who is consuming these messages?"_
+- _And the list goes on..._
+
+Time is lost hunting through multiple tools to find the answers to these questions.
+
+**What if you could answer these questions in minutes?**
+
+EventCatalog is designed to help you avoid the chaos, by providing a way to document your architecture, visualize it, and provide tools to help your teams and AI tools to save time and get answers to the questions when they need them.
+
+---
+
+## What is EventCatalog?
+
+[EventCatalog is a self-hosted open source project](https://github.com/event-catalog/eventcatalog) to help you bring discoverability to your architecture through documentation, visualization, and design for both humans and AI.
+
+EventCatalog models your architecture as structured, versioned knowledge — not just pages of documentation — so it can be searched, visualized, and queried reliably over time.
+
+**EventCatalog is technology agnostic**, you can use it and integrate with any broker, schema format, or stack.
+
+#### What can EventCatalog do for you?
+
+- **Save time and help your teams find answers fast**
+  - Search your entire architecture — domains, services, events, data products, schemas, owners — in seconds
+  - Stop asking "who owns this?" or "what consumes this event?"
+- **Keep documentation and specifications in sync**
+  - Auto-generate docs from your OpenAPI, AsyncAPI, or schema registries
+  - Documentation that updates when your specs update
+  - Write custom integrations with the [EventCatalog SDK](/docs/sdk)
+- **Query your architecture with AI**
+  - Connect AI tools to your architecture using [EventCatalog's MCP server](/docs/development/ask-your-architecture/mcp-server/introduction)
+  - Ask architectural questions grounded in your documented domains, services, events, data products, and schemas
+- **See the bigger picture**
+  - Visualize your architecture, domains, services, and message flows
+  - Document business workflows and draft new ideas
+  - Understand how everything connects — without digging through code
+- **Design what's next**
+  - Capture business workflows and plan changes visually
+  - Use your real architecture as building blocks
+
+**EventCatalog is self-hosted. You own your data and host it wherever you want.**
+
+---
+
+## Why we built this
+
+Event-driven architectures start simple but grow complex fast. More services, more events, more teams — and suddenly nobody knows how anything connects.
+
+EventCatalog brings discoverability, documentation, and visualization to your architecture — so teams can reason about change before it happens, not after.
+
+<details>
+<summary>🎥 Watch: "Complexity is the Gotcha of Event-driven Architecture"</summary>
+<iframe width="100%" height="415" src="https://www.youtube.com/embed/VLUvfIm9wnQ?si=XEEkOqHyZBynqZHo" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
+</details>
+
+---
+
+## Join the community
+
+- [GitHub](https://github.com/event-catalog/eventcatalog) — Star, contribute, report issues
+- [Discord](https://eventcatalog.dev/discord) — Ask questions, share feedback
+
+## Something missing?
+
+If you find issues with the documentation or have suggestions on how to improve the documentation or the project in general, please [file an issue](https://github.com/event-catalog/eventcatalog) for us.

package/dist/docs/development/01-fundamentals.md

@@ -0,0 +1,34 @@
+---
+sidebar_position: 2
+slug: /development/getting-started/fundamentals
+keywords:
+- EventCatalog introduction
+sidebar_label: Fundamentals
+title: Fundamentals
+description: Understanding the fundamentals of EventCatalog
+---
+
+EventCatalog allows you to document your [domains](/docs/development/guides/domains/introduction), [services](/docs/development/guides/services/introduction), [messages](/docs/development/guides/messages/overview) ([events](/docs/development/guides/messages/events/introduction), [commands](/docs/development/guides/messages/commands/introduction), [queries](/docs/development/guides/messages/queries/introduction)), [data products](/docs/development/guides/data-products/introduction), [data stores](/docs/development/guides/data/introduction), [diagrams](/docs/development/guides/diagrams/introduction), [schemas](/docs/development/guides/schemas/introduction), [specifications](/docs/development/guides/services/adding-to-services/openapi) and more.
+
+You can manually document these resources or you can automate the documentation process using EventCatalog integrations (e.g. [OpenAPI](/integrations/openapi), [AsyncAPI](/integrations/asyncapi), [GraphQL](/integrations/graphql) or schema registries), it's up to you.
+
+EventCatalog is flexible and can fit any workflow you have. Deploy it once a day, or 100 times a day. Connect it to external systems like schema registries, API management platforms, or your own custom integrations.
+
+EventCatalog is powered by [markdown files (MDX)](https://mdxjs.com/) and can be used in any markdown editor or IDE.
+
+### Docs-as-code
+
+EventCatalog is a [docs-as-code](https://www.writethedocs.org/guide/docs-as-code/) tool. This means you can store your documentation in your existing Git repository, version it, and use your existing workflows to review and merge changes.
+
+| Pattern | Description |
+|---------|-------------|
+| **Standalone repo** | Keep documentation separate from code |
+| **Next to your code** | Docs live alongside the services they describe |
+| **Monorepo** | Documentation as part of your existing monorepo |
+| **Federated** | Multiple EventCatalog instances connected into one view |
+
+EventCatalog does not force you to use a specific broker, schema format, or stack. You can use it with any broker, schema format, or stack and can fit into any workflow you have. EventCatalog fits your workflow, not the other way around.
+
+## Ready to build?
+
+Now that you understand the fundamentals, [get started with EventCatalog](/docs/development/getting-started/installation).

package/dist/docs/development/01-getting-started/_category_.json

@@ -0,0 +1,12 @@
+{
+  "label": "Getting Started",
+  "position": 3,
+  "collapsible": false,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "slug": "development/getting-started",
+    "title": "Getting Started Documentation",
+    "description": "Learn how to install EventCatalog."
+  }
+}

package/dist/docs/development/01-getting-started/configuration-overview.md

@@ -0,0 +1,124 @@
+---
+sidebar_position: 6
+keywords:
+- EventCatalog configuration
+sidebar_label: Configuration
+title: Configuration
+description: Understand how to configure EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+Most new EventCatalog projects are ready to run as soon as they are created. You only need to change configuration when you want to adjust how the catalog behaves, where it builds, or which features are enabled.
+
+Configuration lives in `eventcatalog.config.js` at the root of your project.
+
+Use this file for catalog-level settings, such as the catalog title, organization name, build output, deployment path, and integrations.
+
+## Start with the generated config
+
+When you create a new EventCatalog project, the starter creates an `eventcatalog.config.js` file for you. For many catalogs, you can leave this file alone while you create your first domains, services, and messages.
+
+Your config may look something like this:
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  cId: '107fdebb-7c68-42cc-975d-413b1d30d758',
+  title: 'EventCatalog',
+  organizationName: 'Your Company',
+};
+```
+
+- `cId` is generated for your catalog. Keep the generated value.
+- `title` is the name shown in your catalog.
+- `organizationName` identifies the team or company that owns the catalog.
+
+## Common changes
+
+You do not need to learn every configuration option up front. These are the settings most teams change first:
+
+The examples below show only the option being changed. Keep the other values that already exist in your config.
+
+### Change the catalog name
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  title: 'Acme Architecture Catalog',
+  organizationName: 'Acme',
+};
+```
+
+### Change the build output
+
+By default, EventCatalog builds a static website that can be hosted almost anywhere.
+
+Some features require EventCatalog to run as a server. You can switch the build output with the `output` option.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  output: 'server',
+};
+```
+
+Learn more about build output in the [configuration API](/docs/api/config#output).
+
+### Configure a deployment base path
+
+If your catalog is hosted under a sub-path, configure `base`.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  base: '/architecture/',
+};
+```
+
+For a catalog hosted at the root of a domain, keep the default `/`.
+
+## Full configuration reference
+
+This page only covers the basics. When you need the complete list of options, use the [eventcatalog.config.js API reference](/docs/api/config).
+
+Configuration guides for specific features live near the feature they configure. For example:
+
+- [Adding Analytics](/docs/development/guides/adding-analytics)
+- [RSS feeds](/docs/api/config#rss)
+- [Authentication](/docs/development/authentication/introduction)
+- [Deployment](/docs/development/deployment/build-and-deploy)
+
+## Configuring environment variables {#configuring-environment-variables}
+
+<AddedIn version="2.35.4" />
+
+Some features need values that should not live directly in `eventcatalog.config.js`, such as license keys or provider credentials.
+
+Put those values in a `.env` file in the root of your catalog. EventCatalog loads `.env` when it runs locally and when it builds.
+
+```bash title=".env (example)"
+EVENTCATALOG_SCALE_LICENSE_KEY=your-api-key
+```
+
+Do not commit real secrets to source control.
+
+## Related configuration
+
+EventCatalog has a linter that can be used to validate your EventCatalog documentation.
+
+You can read more about the EventCatalog Linter in the [EventCatalog Linter documentation](/docs/development/developer-tools/eventcatalog-linter).
+
+### Advanced: disable channel migration
+
+On startup, EventCatalog automatically migrates legacy `channels` definitions on messages to the service-level channels shape.
+
+Most new catalogs do not need to change this behavior. If you are working with an older catalog and want to leave legacy channel definitions untouched, set `EVENTCATALOG_DISABLE_CHANNEL_MIGRATION`.
+
+**Accepted values:** `true`, `1`, or `yes` (case-insensitive). Any other value, or leaving the variable unset, keeps the default behavior: the migration runs as normal.
+
+```bash
+EVENTCATALOG_DISABLE_CHANNEL_MIGRATION=true npx @eventcatalog/core dev
+```
+
+You can also set it in your `.env` file:
+
+```bash title=".env"
+EVENTCATALOG_DISABLE_CHANNEL_MIGRATION=true
+```

package/dist/docs/development/01-getting-started/develop-and-build.md

@@ -0,0 +1,71 @@
+---
+sidebar_position: 5
+keywords:
+- EventCatalog Develop and build
+sidebar_label: Develop and build
+title: Develop and build
+description: Understanding how to develop and build EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+## Edit your project
+
+To make changes to your project, open your project folder in your code editor. Working in development mode with the dev server running allows you to see updates to your site as you edit the code.
+
+## Starting the development server
+
+EventCatalog comes with a built-in development server that has everything you need for project development. The `eventcatalog dev` CLI command will start the local development server so that you can see your new website in action for the very first time.
+
+Every starter template comes with a pre-configured script that will run `eventcatalog dev` for you. After navigating into your project directory, run this command and start the EventCatalog development server:
+
+```bash
+npm run dev
+```
+If all goes well, EventCatalog will now be serving your project on http://localhost:3000/. Visit that link in your browser and see your new site!
+
+## Build and preview your catalog
+
+To check the version of your site that will be created at build time, quit the dev server (Ctrl + C) and run the appropriate build command in your terminal:
+
+```bash
+npm run build
+```
+
+EventCatalog will build a deploy-ready version of your site in a separate folder (dist/ by default) and you can watch its progress in the terminal. This will alert you to any build errors in your project before you deploy to production.
+
+When the build is finished, run the appropriate preview command (e.g. npm run preview) in your terminal and you can view the built version of your site locally in the same browser preview window.
+
+Note that this previews your code as it existed when the build command was last run. This is meant to give you a preview of how your site will look when it is deployed to the web. Any later changes you make to your code after building will not be reflected while you preview your site until you run the build command again.
+
+Use (Ctrl + C) to quit the preview and run another terminal command, such as restarting the dev server to go back to working in development mode which does update as you edit to show a live preview of your code changes.
+
+
+## EventCatalog static vs server output
+
+By default, EventCatalog will build a static website. This means you can [host this website](/docs/development/deployment/hosting-options) anywhere you like.
+
+Some features of EventCatalog (e.g SSO) require a to run EventCatalog as a server.
+
+You can opt into which build mode you want to use by setting the [`output` property in your `eventcatalog.config.js` file](/docs/api/config#output).
+
+
+<!-- ## Supported plugins
+
+EventCatalog uses [MDX](https://mdxjs.com/) file format for documentation.
+
+If you are using VSCode you can install the [MDX](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) plugin, for the `.mdx` files.
+
+Recommended Plugins:
+    - https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx
+    - https://marketplace.visualstudio.com/items?itemName=astro-build.astro-vscode -->
+
+## Next Steps
+
+Success! You are now ready to start building with EventCatalog! 🥳
+
+Here are a few things that we recommend exploring next. You can read them in any order. You can even leave our documentation for a bit and go play in your new EventCatalog project codebase, coming back here whenever you run into trouble or have a question.
+
+- [Create your first domain](/docs/development/guides/domains/creating-domains/adding-domains)
+- [Create your first service](/docs/development/guides/services/adding-services)
+- [Create your first message](/docs/messages)

package/dist/docs/development/01-getting-started/installation.md

@@ -0,0 +1,103 @@
+---
+sidebar_position: 3
+keywords:
+- EventCatalog installation install
+sidebar_label: Installation
+title: Installation
+description: Install EventCatalog and create a new catalog
+---
+
+The `create-eventcatalog` CLI command is the fastest way to start a new EventCatalog project. It creates a catalog directory, installs what you need, and gives you scripts for local development and production builds.
+
+You can also start from a template, create an empty catalog, or use the EventCatalog AI skill to generate documentation from an existing codebase.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/en/download/) v22 or higher. Check your version with `node -v`.
+- A terminal to run the EventCatalog CLI.
+- A text editor to edit your catalog files.
+
+## Install from the CLI wizard
+
+Run the following command in your terminal:
+
+```bash
+npx @eventcatalog/create-eventcatalog@latest my-catalog
+```
+
+This creates a `my-catalog` directory with:
+
+- an EventCatalog project
+- sample architecture resources
+- an `eventcatalog.config.js` file
+- a `package.json` file with scripts for local development and builds
+
+Now move into your new project directory:
+
+```bash
+cd my-catalog
+```
+
+If the CLI asks whether to install dependencies and you skip that step, install them before continuing:
+
+```bash
+npm install
+```
+
+## Start the development server
+
+Start EventCatalog locally:
+
+```bash
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) to view your catalog.
+
+## CLI installation flags
+
+You can pass flags to `create-eventcatalog` to customize the catalog that gets created.
+
+### Create an empty catalog
+
+Use `--empty` when you want a clean catalog without sample resources.
+
+```bash
+npx @eventcatalog/create-eventcatalog@latest my-catalog --empty
+```
+
+### Use a starter template
+
+Use `--template` to start from one of the EventCatalog integration templates.
+
+```bash
+npx @eventcatalog/create-eventcatalog@latest my-catalog --template asyncapi
+```
+
+Templates are useful when you already know which integration you want to use, such as AsyncAPI, OpenAPI, EventBridge, GitHub, or a schema registry.
+
+## Generate a catalog from an existing codebase
+
+If you already have a codebase, you can use the [Catalog Documentation Creator](https://github.com/event-catalog/skills) AI skill to generate EventCatalog documentation from the information in your project.
+
+First, add the EventCatalog skill to your project:
+
+```bash
+npx skills add event-catalog/skills --skill catalog-documentation-creator
+```
+
+Then ask your AI agent to inspect your codebase and generate EventCatalog documentation:
+
+```txt
+Look at my directory and generate EventCatalog documentation from information you find.
+```
+
+The generated files can be edited like any other EventCatalog documentation. Learn more about [EventCatalog skills](/docs/development/ask-your-architecture/skills/introduction).
+
+## Next steps
+
+- [Understand the project structure](/docs/development/getting-started/project-structure)
+- [Develop and build your catalog](/docs/development/getting-started/develop-and-build)
+- [Create your first domain](/docs/development/guides/domains/creating-domains/adding-domains)
+- [Create your first service](/docs/development/guides/services/adding-services)
+- [Document your first message](/docs/development/guides/messages/overview)