Skip to main content

Installation

Getting up and running with EventCatalog should take a few minutes (hopefully!).

Requirements​

  • Node.js version >= 16.14.0 or above (which can be checked by running node -v). You can use nvm for managing multiple Node versions on a single machine installed
  • Yarn version >= 1.5 (which can be checked by running yarn --version). Yarn is a performant package manager for JavaScript and replaces the npm client. It is not strictly necessary but highly encouraged.

Scaffold project website​

The easiest way to install EventCatalog is to use the command line tool that helps you scaffold a skeleton EventCatalog website. 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
├── services
│   ├── Basket Service
│   │     └──index.md
│   ├── Data Lake
│   │     └──index.md
│   ├── Payment Service
│   │     └──index.md
│   ├── Shipping Service
│   │     └──index.md
├── events
│   ├── AddedItemToCart
│   │     └──versioned
│   │     │  └──0.0.1
│   │     │     └──index.md
│   │     │     └──schema.json
│   │     └──index.md
│   │     └──schema.json
│   ├── OrderComplete
│   │     └──index.md
│   │     └──schema.json
│   ├── OrderConfirmed
│   │     └──index.md
│   │     └──schema.json
│   ├── OrderRequested
│   │     └──index.md
│   ├── PaymentProcessed
│   │     └──index.md
├── static
│   └── img
├── eventcatalog.config.js
├── package.json
├── README.md
└── yarn.lock

Project structure rundown​

  • /services/ - Contains the service Markdown files within your Architecture. These are optional but recommended. More details can be found in the services guide
  • /events/ - Contains your Event-Driven Architecture Events. These folders and files can contain markdown, schemas and much more. More details can be found in the events guide
  • /static/ - Static directory. Any contents inside here will be copied into the root of the final build directory. You can add your own logo here and favicon. More details can be found in the customise 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

By default, a browser window will open at http://localhost:3000.

Congratulations! You have just created your first EventCatalog site!

Build​

EventCatlaog uses NextJS under the hood. To build the website run the following command:

npm run build

and contents will be generated within the /out directory. EventCatalog utilises a server to get access to files and much more...

This means you will need to run EventCatalog on a server.

Check out the docs on deployment for more details.