# Configuration

Copy as Markdown[View as Markdown](/docs/development/getting-started/configuration-overview.md)

***

Most new EventCatalog projects are ready to run as soon as they are created. You only need to change configuration when you want to adjust how the catalog behaves, where it builds, or which features are enabled.

Configuration lives in `eventcatalog.config.js` at the root of your project.

Use this file for catalog-level settings, such as the catalog title, organization name, build output, deployment path, and integrations.

## Start with the generated config[​](#start-with-the-generated-config "Direct link to Start with the generated config")

When you create a new EventCatalog project, the starter creates an `eventcatalog.config.js` file for you. For many catalogs, you can leave this file alone while you create your first domains, services, and messages.

Your config may look something like this:

eventcatalog.config.js

```
module.exports = {
  cId: '107fdebb-7c68-42cc-975d-413b1d30d758',
  title: 'EventCatalog',
  organizationName: 'Your Company',
};
```

* `cId` is generated for your catalog. Keep the generated value.
* `title` is the name shown in your catalog.
* `organizationName` identifies the team or company that owns the catalog.

## Common changes[​](#common-changes "Direct link to Common changes")

You do not need to learn every configuration option up front. These are the settings most teams change first:

The examples below show only the option being changed. Keep the other values that already exist in your config.

### Change the catalog name[​](#change-the-catalog-name "Direct link to Change the catalog name")

eventcatalog.config.js

```
module.exports = {
  title: 'Acme Architecture Catalog',
  organizationName: 'Acme',
};
```

### Change the build output[​](#change-the-build-output "Direct link to Change the build output")

By default, EventCatalog builds a static website that can be hosted almost anywhere.

Some features require EventCatalog to run as a server. You can switch the build output with the `output` option.

eventcatalog.config.js

```
module.exports = {
  output: 'server',
};
```

Learn more about build output in the [configuration API](/docs/api/config.md#output).

### Configure a deployment base path[​](#configure-a-deployment-base-path "Direct link to Configure a deployment base path")

If your catalog is hosted under a sub-path, configure `base`.

eventcatalog.config.js

```
module.exports = {
  base: '/architecture/',
};
```

For a catalog hosted at the root of a domain, keep the default `/`.

## Full configuration reference[​](#full-configuration-reference "Direct link to Full configuration reference")

This page only covers the basics. When you need the complete list of options, use the [eventcatalog.config.js API reference](/docs/api/config.md).

Configuration guides for specific features live near the feature they configure. For example:

* [Adding Analytics](/docs/development/guides/adding-analytics.md)
* [RSS feeds](/docs/api/config.md#rss)
* [Authentication](/docs/development/authentication/introduction.md)
* [Deployment](/docs/development/deployment/build-and-deploy.md)

## Configuring environment variables[​](#configuring-environment-variables "Direct link to Configuring environment variables")

**Added in** `eventcatalog@2.35.4`

Some features need values that should not live directly in `eventcatalog.config.js`, such as license keys or provider credentials.

Put those values in a `.env` file in the root of your catalog. EventCatalog loads `.env` when it runs locally and when it builds.

.env (example)

```
EVENTCATALOG_SCALE_LICENSE_KEY=your-api-key
```

Do not commit real secrets to source control.

## Related configuration[​](#related-configuration "Direct link to Related configuration")

EventCatalog has a linter that can be used to validate your EventCatalog documentation.

You can read more about the EventCatalog Linter in the [EventCatalog Linter documentation](/docs/development/developer-tools/eventcatalog-linter.md).

### Advanced: disable channel migration[​](#advanced-disable-channel-migration "Direct link to Advanced: disable channel migration")

On startup, EventCatalog automatically migrates legacy `channels` definitions on messages to the service-level channels shape.

Most new catalogs do not need to change this behavior. If you are working with an older catalog and want to leave legacy channel definitions untouched, set `EVENTCATALOG_DISABLE_CHANNEL_MIGRATION`.

**Accepted values:** `true`, `1`, or `yes` (case-insensitive). Any other value, or leaving the variable unset, keeps the default behavior: the migration runs as normal.

```
EVENTCATALOG_DISABLE_CHANNEL_MIGRATION=true npx @eventcatalog/core dev
```

You can also set it in your `.env` file:

.env

```
EVENTCATALOG_DISABLE_CHANNEL_MIGRATION=true
```