Skip to main content

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.