---
sidebar_position: 3
keywords:
- Upgrade EventCatalog
sidebar_label: v2 
title: Upgrade to EventCatalog v2
description: How to upgrade to EventCatalog v2.
---

This guide will help you upgrade from v1 to v2 of EventCatalog.

EventCatalog v2 comes with some small breaking changes to your EventCatalog.

:::info Still want to use v1?

**Still using v1 of EventCatalog?** V1 documentation can be found at https://v1.eventcatalog.dev/

You can find the code for v1 on the branch https://github.com/event-catalog/eventcatalog/tree/v1

We recommended to upgrade to v2 as support for v1 changes will be reduced.

:::

## Migrating to version 2

EventCatalog v2 has been rewritten from the ground up. The easiest way to migrate to version 2 is following these steps:

1. [Create a new Catalog](/docs/development/getting-started/installation)
1. Delete the `domains`, `services`, `commands` and `events` folder.
1. Copy your `eventcatalog.config.js` and `domains`, `services`, `events` folders into the new catalog.
1. Add `ids` to all your resources ([read more](/docs/starting-a-new-project/getting-started#resources-now-require-ids))
1. If your resource are in a nested structure [you need to flatten these out](/docs/starting-a-new-project/getting-started#resources-require-a-flat-structure).

:::tip Having problems?
If you are still having issues upgrading your catalog, [then please raise an issue on our GitHub repo.](https://github.com/event-catalog/eventcatalog/issues).
:::


## Resources now require ids

**All domains, services and events need an id property in the frontmatter**. EventCatalog uses this `id` as the slug of the page and uses it as internal references.

#### Example
```md
---
# id is now required on all resources (domains, services and messages)
id: order-service
name: Order Service
# rest of frontmatter..
---
<!-- Your markdown content -->
```

## Resources require a flat structure

In EventCatalog v1 you could nest your resources for example have your events or services within your domains folder. (Example /domains/services/MyService/index.mdx)

This feature is not currently supported in version 2.

Version 2 requires your domains, services and messages (commands, and events) to be in the root directory.

## Change to build output

The build output has changed from v1 from being `out` directory to `dist` directory in version 2.

## Any other issues?

If you have any issues or questions please [feel free to reach us on Discord](https://discord.com/invite/3rjaZMmrAm).

