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!

Configuring environment variables​

Added in eventcatalog@2.35.4

EventCatalog can use environment variables to configure the site, depending on what features you are using (e.g plugins or plans).

If you are using EventCatalog Plugins, or any EventCatalog Plans you can put these into your .env file.

.env
EVENTCATALOG_SCALE_LICENSE_KEY=your-api-key
Understanding EventCatalog License Keys and Plans

EventCatalog community edition is free to use and does not require a license key.

Some features of EventCatalog require a license key, these include:

You can get a 14 day free trial of any of the plans here. Once you get the license key you can put it in your .env file.

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.

Static website output​

By default EventCatalog will build a static website, so you can host this website anywhere you like.

Check out the docs on hosting for more details.

Server output​

Added in eventcatalog@2.35.4

If you have configured a server output in your eventcatalog.config.js file, EventCatalog will build a server.

A server output is required if you are using any EventCatalog feature that requires a server, these include:

You can use the Docker image to run the server, this is the recommended way to run the server.

Check out the docs on hosting for more details.