Skip to main content

Creating channels

Added in eventcatalog@2.13.0

Adding a channel to your Catalog is a great way for you to document how your messages communicate between services.

What do channels look like in EventCatalog?​

Example View demo

Adding a new channel​

To add a new channel create a new folder within the /channels folder with an index.mdx file.

  • /channels/{Channel Name}/index.mdx
    • (example /channels/EventsChannel/index.mdx)
    • (example /channels/inventory.{env}.events/index.mdx)
    • (example /channels/EventBus/index.mdx)

The index.mdx contents are split into two sections, frontmatter and the markdown content.

Here is an example of what a channel markdown file may look like. You can read the API docs for the channel front matter API

/channels/inventory.{env}.events/index.mdx (example)
---
# id of your channel, used for slugs and references in EventCatalog.
# this channel is using dynamic naming using parameters
id: inventory.{env}.events

# Display name of the Channel, rendered in EventCatalog
name: Inventory channel

# Version of the Channel
version: 0.0.1

# Short summary of your Channel
summary: |
  Central event stream for all inventory-related events including stock updates, allocations, and adjustments

# Optional owners, references teams or users
owners:
    - dboyne

# Address of the channel, this example shows a kafka address with parameters, but it can be anything
address: inventory.{env}.events

# optionally document the params for your channel name
# here we know that the channel address "env" value can be "dev,stg,or prod"
parameters:
  env:
    enum:
      - dev
      - stg
      - prod
    description: 'Environment to use'
---

### Overview

The Inventory Events channel is the central stream for all inventory-related events across the system. This includes stock level changes, inventory allocations, adjustments, and stocktake events. Events for a specific SKU are guaranteed to be processed in sequence when using productId as the partition key.

<!-- Shows channel information on the page including a table of all your params and their values -->
<ChannelInformation />

<!-- Rest of markdown -->

That's it!

Once you add your new channel to EventCatalog, it will now show in the catalog.

With channels you can write any Markdown you want and it will render on your page. Every channel gets its own page.

Within your markdown content you can use components to add interactive components to your page.

If you want to see some examples you can look at the EventCatalog demo on GitHub.

Using parameters in channel names​

You may have some channel names/addresses that are dynamic. For example address: inventory.{env}.events.

The channel address: inventory.{env}.events shows us the channel name is dynamic with the given parameter env.

In your channel you can document your parameters, give them values, default values and descriptions.

---
# channel markdown file.

# The dynamic address
address: inventory.{env}.events

# optionally document the params for your channel name
# here we know that the channel address "env" value can be "dev,stg,or prod"
parameters:
  env:
    # What values for the parameter? (optional)
    enum:
      - dev
      - stg
      - prod
    # what is the default value (optional)
    default: dev
    # Any examples if you want to list them
    examples: 
      - dev
      - stg
      - prod
    # Describe the channel information (optional)
    description: 'Environment to use'
---

Once this information is defined, it can then be rendered on your page using the <ChannelInformation /> component.

Example output using the <ChannelInformation /> component​

Example

Using protocols in channels​

Your channel can have one or many protocols. To define a protocol you add the property to your channel.

---
id: inventory.{env}.events

# rest of channel markdown...

# You can define one or many protocols
# list of protocols: https://eventcatalog.dev/docs/development/guides/channels/introduction#protocols
protocols:
  - http
  - kafka
  - mqtt
---

These protocols will be displayed on your channel page and the visualizer.

You can get the list of protocols here.