Skip to main content
⭐️ If you love EventCatalog, give it a star on GitHub. Thanks!

Installation

Requirements

  • Node.js version >= 20.x.x or above (which can be checked by running node -v). You can use nvm for managing multiple Node versions on a single machine installed

Scaffold project catalog

The easiest way to install EventCatalog is to use the command line tool that helps you scaffold a skeleton EventCatalog. You can run this command anywhere in a new empty repository or within an existing repository, it will create a new directory containing the scaffolded files.

npx @eventcatalog/create-eventcatalog@latest [name]

Example:

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

Project structure

Assuming you named your site my-catalog, you will see the following files generated under a new directory my-catalog/:

my-catalog
├── /domains
│ ├── /Orders
│ │ └──index.md
│ │ └──/versioned
│ │ └──0.0.1
│ │ └──index.md
│ └── /Payment
│ └──index.md
├── /services
│ ├── /InventoryService
│ │ └──index.md
│ ├── /NotificationService
│ │ └──index.md
│ ├── /OrdersService
│ │ └──index.md
│ │ └──openapi.yml
│ └── /PaymentService
│ └──index.md
├── /commands
│ ├── /AddInventory
│ │ └──index.md
│ ├── /UpdateInventory
│ │ └──index.md
├── /events
│ ├── /Inventory
│ │ ├── /InventoryAdjusted
│ │ │ └──index.md
│ │ │ └──schema.json
│ │ │ └──/versioned
│ │ │ └──0.0.1
│ │ │ └──index.md
│ │ │ └──schema.json
│ ├── OutOfStock
│ │ └──index.md
├── teams
│ └──full-stack.md
│ └──mobile-devs.md
├── users
│ └──aSmith.md
│ └──dboyne.md
│ └──mSmith.md
├── eventcatalog.config.js
├── package.json
└── README.md

Project structure rundown

  • /domains/ - Contains the domain Markdown files. These are optional but recommended. With domains you can group services. More details can be found in the domains guide
  • /services/ - Contains the service Markdown files. Services belong to a domain, and can send or receive messages (commands or events). These are optional but recommended. More details can be found in the services guide
  • /commands/ - Contains commands (message). These are optional. Learn more in the commands guide
  • /events/ - Contains events (message). These are optional. More details can be found in the events guide
  • /eventcatalog.config.js - A config file containing the site configuration. Read the API docs
  • /package.json - File required for your application to work.

Running the development server

To preview your changes as you edit the files, you can run a local development server that will serve your website and reflect the latest changes.

cd my-catalog
npm run dev

You will be able to see your EventCatalog at http://localhost:3000/docs

Congratulations! You have just created your first EventCatalog site!

Build

EventCatalog uses Astro under the hood. To build the catalog run the following command:

npm run build

All contents will be generated within the /dist directory.

EventCatalog is currently a static website so you can host this folder anywhere you like.

Check out the docs on hosting for more details.