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 my-catalog

Project structure​

You have two ways to document your event-driven architecture:

  • Nested folder structures (default)
    • You can group domains, services and messages together using folders (recommended)
    • This can help you manage large catalogs with folders.
  • Flat folder structures
    • You can have all your resources (domains, services and messages) in the root of your project.
    • This can be useful for simple catalogs.
Nested folder structure example (recommended)
  • /domains/
    • Root folder called domains this folder contains information about your domain and the services that belong to that domain.
      • Example /domains/Orders
    • More details can be found in the domains guide
  • /domains/{Domain Name}/services/
    • Put your services inside your domain folder
      • Example /domains/Orders/services/OrdersService
    • More details can be found in the services guide
  • /domains/{Domain Name}/services/{Service Name}/events
    • Put events inside your service
      • Example /domains/Orders/services/OrdersService/events
    • More details can be found in the events guide
  • /domains/{Domain Name}/services/{Service Name}/commands
    • Put commands inside your service
      • Example /domains/Orders/services/OrdersService/commands
    • More details can be found in the commands guide
  • /domains/{Domain Name}/services/{Service Name}/queries
    • Put queries inside your service
      • Example /domains/Orders/services/OrdersService/queries
    • More details can be found in the queries guide
  • /teams
    • Document teams in EventCatalog
      • Example /teams/myteam.mdx
    • More details can be found in the teams guide
  • /users
    • Document users in EventCatalog
      • Example /users/dboyne.mdx
    • More details can be found in the users guide
  • /eventcatalog.config.js - A config file containing the site configuration. Read the API docs
  • /package.json - File required for your application to work.
Flat folder structure example
  • /domains/
    • Document domains in EventCatalog
      • Example /domains/Orders
    • More details can be found in the domains guide
  • /services/
    • Document services in EventCatalog
      • Example /services/OrdersService
    • More details can be found in the services guide
  • /events
    • Document events in EventCatalog
      • Example /events/InventoryPlaced
    • More details can be found in the events guide
  • /commands
    • Document commands in EventCatalog
      • Example /commands/UpdateInventory
    • More details can be found in the commands guide
  • /queries
    • Document queries in EventCatalog
      • Example /queries/GetInventory
    • More details can be found in the queries guide
  • /teams
    • Document teams in EventCatalog
      • Example /teams/myteam.mdx
    • More details can be found in the teams guide
  • /users
    • Document users in EventCatalog
      • Example /users/dboyne.mdx
    • More details can be found in the users 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.