@eventcatalog/core 3.34.0 → 3.35.1

package/dist/docs/development/customization/customize-sidebars/01-documentation-sidebar.md

@@ -0,0 +1,187 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog documentation sidebar
+sidebar_label: Documentation Sidebar
+title: Documentation sidebar
+description: Pick and customize the documentation sidebar.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+The documentation sidebar is a [context aware sidebar](#what-is-context-aware-sidebar) that is shown on the `/docs/` pages.
+
+Clicking on any resource in the sidebar will show you related information to that selected resource ([see demo](https://demo.eventcatalog.dev/)).
+
+![](./images/docs-sidebar.png)
+
+## What is a context aware sidebar?
+
+**Many documentation tools use a flat navigation structure, which can be overwhelming and difficult to navigate.**
+
+EventCatalog's documentation sidebar is a context aware sidebar that shows you related information to the selected resource.
+
+This can help you navigate your documentation and find the information you need quickly, as you go deeper into the hierarchy of your architecture.
+
+For example, selecting a domain will show you the subdomains, related services, ubiquitous language, etc, where as selecting a message will show you the producers, consumers and schemas.
+
+
+## Customizing the documentation sidebar
+
+By default EventCatalog will show you a list of all the resources in your catalog, but you can customize the navigation bar to show any resource you want.
+
+This can be useful if you want to show a specific resource or a group of resources in the sidebar, helping your teams find the information they need quickly.
+
+### How to customize the documentation sidebar
+
+To customize the documentation sidebar you need to set the `navigation.pages` property in your `eventcatalog.config.js` file.
+
+The example below will show you a list of the top-level domains and all resources in your catalog.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  // ... rest of your config
+  navigation: {
+    // pick any key you want to show in the sidebar
+    pages: ['list:top-level-domains', 'list:all'],
+  },
+};
+```
+
+![](./images/custom-docs-sidebar.png)
+
+#### Available navigation configuration
+
+You can specify the following options in the `navigation.pages` property:
+
+- [Top level options](#top-level-options) 
+  - Useful if you want to show the top-level resources in your catalog in the sidebar. For example high level domains and let your users drill down.
+- [List all resources (by type)](#list-all-resources-type)
+  - Useful if you want to show all resources of a specific type in the sidebar. For example all domains, services, messages, etc.
+- [Pick specific resources to show](#pick-specific-resources-to-show)
+  - Useful if you want to show a specific resource or a group of resources in the sidebar. For example a specific domain, service, message, etc.
+- [Custom groups and links](#custom-groups-and-links)
+  - Useful if you want to create custom groups and links to external pages in the sidebar. For example a group of resources, or a link to an external page.
+
+#### Top level options:
+
+| Key | Description |
+| --- | --- |
+| `list:all` | Lists all resources types in your catalog, organized by resource type (e.g domain, services, messages) |
+| `list:top-level-domains` | Displays a list of the top-level domains in your catalog. (Does not include subdomains) |
+
+**Example**
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  navigation: {
+    pages: ['list:top-level-domains'],
+  },
+};
+```
+
+
+#### List all resources (by type):
+
+| Key | Description |
+| --- | --- |
+| `list:domains` | Lists all domains in your catalog. |
+| `list:services` | Lists all services in your catalog. |
+| `list:messages` | Lists all messages in your catalog. |
+| `list:channels` | Lists all channels in your catalog. |
+| `list:designs` | Lists all designs in your catalog. |
+| `list:flows` | Lists all flows in your catalog. |
+| `list:containers` | Lists all containers in your catalog. |
+
+**Example**
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  navigation: {
+    pages: ['list:domains', 'list:services'],
+  },
+};
+```
+
+#### Chose which resources to show:
+
+You can specify any resource you want to show in the sidebar using the following key structure
+
+`<resource-type>:<resource-id>` or `<resource-type>:<resource-id>:<resource-version>`
+
+*If no version is specified, the latest version will be used.*
+
+*Example:*
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  navigation: {
+    // Show the MyDomain domain, MyService service and the 0.0.1 version of the MyEvent event
+    pages: [
+      // Show the latest version of the MyDomain domain
+      'domain:MyDomain',
+      // Show the latest version of the MyService service
+      'service:MyService',
+      // Show the 0.0.1 version of the MyMessage message
+      'message:MyMessage:0.0.1',
+    ],
+  },
+};
+```
+
+Available resource types:
+| Resource Type | Description |
+| --- | --- |
+| `domain` | Domain resource type. |
+| `service` | Service resource type. |
+| `message` | Message resource type. |
+| `channel` | Channel resource type. |
+| `design` | Design resource type. |
+| `flow` | Flow resource type. |
+| `container` | Container resource type. |
+| `user` | User resource type. |
+| `team` | Team resource type. |
+| `event` | Event resource type. |
+| `command` | Command resource type. |
+| `query` | Query resource type. |
+
+### Custom groups and links
+
+You can also create custom groups and links to external pages in the sidebar.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  navigation: {
+    pages: [
+      // Custom group
+      {
+        type: 'group',
+        // Custom group title
+        title: 'My Custom Group',
+        // Custom group icon from lucide icons
+        icon: 'Boxes',
+        // Custom group pages
+        pages: [
+          // You can still reference resources, lists as you would normally do
+          'domain:E-Commerce',
+          // Create a custom item link to an external page
+          {
+            type: 'item',
+            title: 'My Custom Link',
+            // Custom link to an external page
+            href: 'https://eventcatalog.dev',
+          }
+        ],
+      },
+      // Or have a custom item on the root (outside a group)
+      {
+        type: 'item',
+        title: 'My Custom Item',
+        href: 'https://eventcatalog.dev',
+      }
+      // You can still use EventCatalog lists or resources as you would normally do
+      'list:all',
+    ]
+  },
+};
+```

package/dist/docs/development/customization/customize-sidebars/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Customize Sidebars",
+  "position": 3,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/customize-sidebars",
+    "description": "A collection of guides to help you customize the sidebars in your catalog."
+  }
+}

package/dist/docs/development/customization/customize-visualizer/00-visualizer-nodes.md

@@ -0,0 +1,50 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog visualizer nodes 
+sidebar_label: Customize nodes
+title: Customize visualizer nodes
+description: Customize the color, label and icon of the visualizer nodes.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.33.8" />
+
+Every node in the visualizer has a color, label and icon. 
+
+The example below shows the default node for a **Service** resource.
+
+<!-- Image image -->
+![Visualizer Node](./img/customize-node.png)
+
+By default the icon, color and label in the node is generated by EventCatalog. Helping you maintain consistency across your catalog.
+
+You can use the `styles` property to customize the icon, color and label of the node, if you want to customize the node to be more specific to your use case.
+
+```md title="/domains/MyDomain/services/MyService.md"
+---
+id: NotificationService
+version: 0.0.2
+name: Notification Service
+summary: |
+  Service that handles orders
+styles:
+  icon: "BellIcon"
+  node: 
+    color: purple
+    label: "Custom"
+---
+```
+
+#### Rendered output
+
+![Customized Node](./img/customize-node-example.png)
+
+### Configuration
+
+| ID | Required | Default | Description |
+| --- | --- | --- | --- |
+| `styles.icon` | No | Depends on resource type | The icon to use for the resource. Icons are from [hero icons](https://heroicons.com/). <br/> You can find a list of icons [here](https://unpkg.com/browse/@heroicons/react@2.1.5/24/outline/). |
+| `styles.node.color` | No | Depends on resource type | The color to use for the node. These are tailwind colors and you can find a list of them [here](https://tailwindcss.com/docs/colors). |
+| `styles.node.label` | No | Depends on resource type | The label to use for the node (side label). |

package/dist/docs/development/customization/customize-visualizer/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Customize Visualizer",
+  "position": 4,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/customize-visualizer",
+    "description": "A collection of guides to help you customize the visualizer in your catalog."
+  }
+}

package/dist/docs/development/deployment/_category_.json

@@ -0,0 +1,12 @@
+{
+  "label": "Deployment",
+  "position": 12,
+  "collapsible": false,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "slug": "development/deployment",
+    "title": "Deployment guides",
+    "description": "This section contains deployment tutorials for developers. This includes tutorials for deploying to Heroku, AWS, and other cloud providers."
+  }
+}

package/dist/docs/development/deployment/build-and-deploy.md

@@ -0,0 +1,71 @@
+---
+sidebar_position: 5
+keywords:
+- build
+- deploy
+sidebar_label: Build (Static Mode)
+title: Building Eventcatalog
+description: This document describes step by step how to deploy EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+By default, EventCatalog exports a static HTML site. This means you can deploy your application anywhere you want.
+
+:::tip Have large or slow deployments?
+Some users have large catalogs, and slow deployments. This is because the static mode builds the entire catalog into HTML files.
+
+If you have a large catalog you may want to use [SSR mode](/docs/development/deployment/build-ssr-mode), this will give you a server-side rendered application. 
+This reduces build times, and renders pages on the fly. 
+:::
+
+
+## Building your EventCatalog (Static)
+
+To build your Catalog you will need to run:
+
+```bash
+npm run build
+```
+
+This will output one directory
+
+- `dist` - Your EventCatalog as Static HTML
+
+### Passing custom options
+
+<AddedIn version="2.16.5" />
+
+EventCatalog uses [Astro](https://astro.build/) to build the application. You can pass custom options to the build command by using the `--` prefix.
+
+```bash title="Passing custom options"
+npx eventcatalog dev --debug -- --env=production --port=3000
+```
+
+### Compression
+
+You can opt into our build step which will compress your static assets. 
+
+You can enable this by setting the [compress option](/docs/api/config#compress) to `true` in your `eventcatalog.config.js` file.
+
+:::info "Why is compression disabled by default?"
+Compression can increase your build time and the amount of memory required to build your catalog.
+
+If you want to enable this feature, you might also want to increase your build memory using the `max_old_space_size` value.
+:::
+
+### Memory limits
+
+If you get any `JavaScript heap out of memory` errors, you can increase the memory limit by setting the `NODE_OPTIONS` environment variable. This gives astro more memory to work with.
+
+```bash title="Increasing the memory limit"
+NODE_OPTIONS=--max_old_space_size=8196 npm run build
+```
+
+If you are still experiencing issues, you can try:
+
+
+- Turning off HTML compression ([see documentation](/docs/api/config#compress))
+- Turning on MDX optimization ([see documentation](/docs/api/config#mdxOptimize))
+- Rendering EventCatalog in [SSR mode](/docs/development/deployment/build-ssr-mode). 
+    - This requires you to run your EventCatalog on a server. But your pages are rendered on the fly, so you don't need to build the entire catalog into HTML files. This can also save you a lot of time when deploying your catalog.

package/dist/docs/development/deployment/build-ssr-mode.md

@@ -0,0 +1,50 @@
+---
+sidebar_position: 5
+keywords:
+- build
+- deploy
+sidebar_label: Build (SSR Mode)
+title: Building Eventcatalog
+description: This document describes step by step how to deploy EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+You can also use EventCatalog in SSR mode, which means you can use EventCatalog as a server-side rendered application.
+
+This can be useful for large catalogs, or for users with slow deployment times.
+
+Certain features like **Authentication** and **EventCatalog Chat** require SSR mode.
+
+### How it works
+
+Rather than building the entire catalog into HTML files, EventCatalog will render the pages on the fly (using server-side rendering).
+
+This means you can use EventCatalog as a server-side rendered application.
+
+## Building your EventCatalog (SSR)
+
+First you need to update your `eventcatalog.config.js` file to use SSR mode.
+
+```js title="eventcatalog.config.js"
+export default {
+  // defaults to static
+  output: 'server', 
+}
+```
+
+Next you need to build your EventCatalog
+
+```bash
+npm run build
+```
+
+This will output one directory
+
+- `dist` - Your EventCatalog as a SSR application
+
+## Deployment   
+
+You will need to deploy your EventCatalog to a server that can run Node.js.
+
+The easiest way to do this is to use [a docker container](/docs/development/deployment/hosting-options#hosting-static-website-with-docker).

package/dist/docs/development/deployment/deployment-workflows.md

@@ -0,0 +1,43 @@
+---
+sidebar_position: 5
+keywords:
+- build
+- deploy
+sidebar_label: Deployment Workflows
+title: Deployment Workflows
+description: This document describes different deployment workflows for EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+Many people are deploying EventCatalog in different ways, as it's self hosted you can rebuild and redeploy your catalog as often as you want.
+
+### Keeping EventCatalog up to date
+
+Keeping documentation up to date is a challenge, as it's easy to forget to update the documentation when you make changes to your code.
+
+One way to keep your documentation up to date, is to redeploy your catalog whenever changes are made to your code, specifications or schemas.
+
+EventCatalog has companies redeploying their catalogs hundreds of times a day.... it really depends on how often you make changes to your code, specifications or schemas, and how often you want to update your documentation. **You are in control of how often you redeploy your catalog.**
+
+Many folks using EventCatalog have information scattered across multiple repositories, schema registries and other systems.
+
+Users of EventCatalog either use [our integrations (e.g AsyncAPI, OpenAPI, Schema Registry)](/integrations) or have built their own automated systems using our [SDK](/docs/sdk).
+
+### CI/CD workflow to keep your documentation up to date
+
+EventCatalog is docs-as-code solution. This means you can store EventCatalog next to your code and in git repositories.
+
+You can setup your CI/CD pipeline to build and deploy your catalog whenever changes are made to your code, specifications or schemas.
+
+
+```mermaid LR
+flowchart LR
+    A[Code changes in any repository] --> B[Trigger CI/CD pipeline to build and deploy catalog]
+    B --> C[EventCatalog is rebuilt and deployed]
+```
+
+EventCatalog is flexible. And you can redeploy your catalog in various ways.
+
+This can let you setup automation to ensure your documentation can stay up to date with any changes to your code, specifications or schemas.
+

package/dist/docs/development/deployment/hosting-options.md

@@ -0,0 +1,112 @@
+---
+sidebar_position: 6
+keywords:
+- build
+- deploy
+sidebar_label: Hosting
+title: Hosting
+description: This document describes hosting options for EventCatalog.
+---
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+### Hosting Options
+
+EventCatalog can be hosted in two ways:
+
+- [Hosting a static website output (default)](#hosting-a-static-website)
+- [Hosting EventCatalog Server](#hosting-as-a-server)
+
+### Hosting a static website
+
+By default EventCatalog will build a static website.
+
+Here are some guides and places you can host static content
+
+- [Host with Docker](#hosting-with-docker)
+- [Deploy to NextJS](https://nextjs.org/docs/deployment)
+- [Host in AWS S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/WebsiteHosting.html)
+- [Deploying EventCatalog using Helm chart](https://github.com/osodevops/helm-charts/tree/main/charts/eventcatalog)
+
+**Community posts**
+- [Using AWS CDK to Deploy EventCatalog](https://matt.martz.codes/using-aws-cdk-to-deploy-eventcatalog)
+- [Using Netlify to host Static Content](https://www.netlify.com/blog/2016/10/27/a-step-by-step-guide-deploying-a-static-site-or-single-page-app/)
+- [How to create an EventCatlaog with Azure](https://www.kallemarjokorpi.fi/blog/how-to-create-and-event-catalog.html)
+- [Autonomous EventCatalog for documenting EventBridge Events](https://medium.com/@wrennkieran/autonomous-eventcatalog-for-documenting-eventbridge-events-73e6334f2400)
+
+### Hosting static website with Docker
+
+EventCatalog comes with a DockerFile you can build the image and deploy the container. The container exposes ports `3000`.
+
+To build the docker container you need to run:
+
+```bash
+# Builds the container
+docker build -t eventcatalog .
+
+# Runs the container locally
+docker run -p 3000:80 -it eventcatalog
+```
+
+### Hosting as a server
+
+<AddedIn version="2.35.4" />
+
+First you need to update your `eventcatalog.config.js` file to use SSR mode.
+
+```js title="eventcatalog.config.js"
+export default {
+  // defaults to static
+  output: 'server', 
+}
+```
+
+A server output is required if you are using any EventCatalog feature that requires a server, these include:
+
+- [EventCatalog Chat (bring your own keys)](/features/ai-assistant)
+- [EventCatalog Authentication](/docs/development/authentication/introduction)
+
+You can use the server Docker image to run the server, this is the recommended way to run the server.
+
+First you need to create a Dockerfile for the server (if you don't already have one).
+
+```bash title="/Dockerfile.server"
+FROM node:lts AS runtime
+WORKDIR /app
+
+# Install dependencies
+COPY package.json package-lock.json ./
+RUN npm install
+
+COPY . .
+
+# Fix for Astro in Docker: https://github.com/withastro/astro/issues/2596
+ENV NODE_OPTIONS=--max_old_space_size=2048
+RUN npm run build
+
+ENV HOST=0.0.0.0
+ENV PORT=3000
+EXPOSE 3000
+
+# Start the server
+CMD npm run start
+```
+
+Then you can build the docker image with:
+
+```bash
+docker build -f Dockerfile.server -t eventcatalog-server .
+```
+
+Then you can run the server with:
+
+```bash
+docker run -p 3000:3000 eventcatalog-server
+```
+
+:::info "Why do I need a server to run EventCatalog?"
+
+Some features of EventCatalog require a server to run (e.g. [EventCatalog Chat](/features/ai-assistant) and [EventCatalog Authentication](/docs/development/authentication/introduction)).
+
+If you have a large catalog, you may want to use [SSR mode](/docs/development/deployment/build-ssr-mode) to reduce build times.
+
+:::

package/dist/docs/development/deployment/licenses.md

@@ -0,0 +1,50 @@
+---
+sidebar_position: 5
+keywords:
+- licenses
+sidebar_label: License Validation
+title: EventCatalog Licenses
+description: This document describes how EventCatalog licenses work online and offline.
+---
+
+EventCatalog is an open source project with a [community edition and a commercial edition](/pricing) and also supports a range of integrations (plugins) which have their own licenses.
+
+If you are using the commercial edition of EventCatalog, then you don't need to worry about licenses and can skip this page.
+
+If you are using EventCatalog Starter, EventCatalog Scale, EventCatalog Enterprise or any of the integrations (plugins) you will need to set up a license key.
+
+:::tip Want to try commercial features?
+All licenses have a 14 day free trial. You can get a free trial license key by going to [EventCatalog Cloud](https://eventcatalog.cloud).
+
+If you wish to continue using the commercial features after the trial period, you will need to purchase a license.
+
+You can email us at `hello@eventcatalog.dev` to enquire about a license.
+:::
+
+
+### How to set up a license keys
+
+1. Go to [EventCatalog Cloud](https://eventcatalog.cloud) and sign up for a free trial.
+1. Once you are logged in, you can select any license you want to use or integration.
+1. Selecting the plan or integration will give you a license key. 
+1. Store the license key in your `.env` file or as an environment variable.
+
+### How EventCatalog validates licenses keys
+
+##### Online License Validation (recommended)
+
+By default, EventCatalog will validate your license key online.
+
+Your keys are read from your `.env` file and verified against our API.
+
+##### Offline License Validation
+
+If you are behind a firewall or can't access the EventCatalog API, then your license keys can be validated offline.
+
+To get offline validation working you will need to:
+
+1. Get in contact with us at `hello@eventcatalog.dev` to get a license key `(license.jwt)`.
+1. Once you have you license key `(license.jwt)` you put this into the root of your catalog directory.
+1. EventCatalog will then validate your license key offline.
+
+Your key will expire after a year of purchase, and you will need to get a new license key.

package/dist/docs/development/design/_category_.json

@@ -0,0 +1,12 @@
+{
+  "label": "Designing with Studio",
+  "position": 30,
+  "collapsible": false,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "slug": "design",
+    "title": "Design",
+    "description": "This section describes how to use EventCatalog to design workflows and new ideas."
+  }
+}

package/dist/docs/development/design/embed-designs-into-eventcatalog.md

@@ -0,0 +1,29 @@
+---
+sidebar_position: 4
+keywords:
+- design
+- studio
+- resources
+sidebar_label: Embed Designs into EventCatalog
+title: Embed Designs into EventCatalog
+description: Embed Designs into EventCatalog with EventCatalog
+unlisted: true
+---
+
+You can embed any diagram directly into your documentation using the [`<Design />`](/docs/development/components/components/design) component.
+
+![Embed into EventCatalog](/img/embed-ec.png)
+
+To embed your diagrams you need to:
+
+1. Save your diagram as a `.ecstudio` file
+1. Put your `.ecstudio` file in the location of your markdown file in EventCatalog.
+2. Use the [`<Design />`](/docs/development/components/components/design) component in your markdown file to embed your diagram into your documentation
+
+:::info Embed diagrams anywhere
+
+Our vision to to allow users to be embed diagrams anywhere, letting them embed diagrams into their tools they already use.
+
+This is currently on our roadmap, and we will be adding more support for this in the future.
+
+:::

package/dist/docs/development/design/further-reading.md

@@ -0,0 +1,19 @@
+---
+sidebar_position: 5
+keywords:
+- design
+- studio
+- resources
+sidebar_label: Further Reading
+title: Further Reading
+description: Further Reading with EventCatalog
+unlisted: true
+---
+
+If you want to learn more about EventCatalog Studio you can [read our documentation here](/docs/studio/getting-started) or click on the links below to learn more.
+
+
+
+- [How to add nodes to your diagram](/docs/studio/diagrams/using-nodes)
+- [Adding comments to your designs](/docs/studio/diagrams/adding-comments)
+- [Import & Export your designs](/docs/studio/diagrams/import-export)