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.