# Use local catalogs during development

Copy as Markdown[View as Markdown](/docs/federation/how-to/use-local-sources.md)

***

`EventCatalog Enterprise Feature`

Use filesystem sources to test cross-catalog relationships, ownership conflicts, rules, assets, and custom components before pushing source changes to GitHub.

## Configure a filesystem source[​](#configure-a-filesystem-source "Direct link to Configure a filesystem source")

Set `source` to a `file:` locator:

eventcatalog.config.js

```
export default {
  federation: {
    sources: [
      {
        id: 'acme/payments',
        source: 'file:../payments-catalog',
      },
    ],
  },
};
```

The path after `file:` is resolved from the central catalog directory.

Use `path` when the catalog is inside the selected filesystem source:

eventcatalog.config.js

```
{
  id: 'acme/payments',
  source: 'file:../architecture-catalogs',
  path: 'payments',
}
```

Filesystem sources do not support `ref`.

## Switch the same sources between local and GitHub[​](#switch-the-same-sources-between-local-and-github "Direct link to Switch the same sources between local and GitHub")

Keep each source `id` and `path` stable, and select only the locator with an environment variable:

eventcatalog.config.js

```
const federationSource =
  process.env.EVENTCATALOG_FEDERATION_LOCAL === 'true'
    ? 'file:..'
    : 'github:acme/architecture-catalogs';

export default {
  federation: {
    sources: [
      {
        id: 'acme/orders',
        source: federationSource,
        path: 'orders',
      },
      {
        id: 'acme/payments',
        source: federationSource,
        path: 'payments',
      },
    ],
  },
};
```

Run against the local catalogs:

```
EVENTCATALOG_FEDERATION_LOCAL=true npx eventcatalog federate
```

Run against GitHub:

```
npx eventcatalog federate
```

## Add a local npm script[​](#add-a-local-npm-script "Direct link to Add a local npm script")

For macOS and Linux, add a script to the central catalog:

package.json

```
{
  "scripts": {
    "federate": "eventcatalog federate",
    "federate:local": "EVENTCATALOG_FEDERATION_LOCAL=true eventcatalog federate"
  }
}
```

Then run:

```
npm run federate:local
```

On Windows, set `EVENTCATALOG_FEDERATION_LOCAL` using your shell's environment variable syntax or use a cross-platform environment helper.

## Rerun after source changes[​](#rerun-after-source-changes "Direct link to Rerun after source changes")

Filesystem federation is currently one-shot. When a source catalog changes, rerun:

```
EVENTCATALOG_FEDERATION_LOCAL=true npx eventcatalog federate
```

The EventCatalog development watcher does not automatically rerun Federation for changes in another catalog.

## Understand local revisions[​](#understand-local-revisions "Direct link to Understand local revisions")

Federation creates a content-derived revision such as `local:92400b8dfbe1` for each local source. The value changes when indexed source content changes and is recorded in `eventcatalog.lock`.

This revision identifies the state used by that run. It does not prevent later local edits from being selected by the next run.

## Test a diagnostic[​](#test-a-diagnostic "Direct link to Test a diagnostic")

To test organization-wide validation locally:

1. Add a relationship in one catalog that points to a missing ID.
2. Run local Federation with `--verbose`.
3. Confirm the `federation/missing-resource` warning names the source catalog, referring resource, and missing resource.
4. Add the resource to its owning catalog.
5. Rerun Federation and confirm the warning disappears.

> ***PLACEHOLDER*** — Terminal screenshot showing a locally triggered federation diagnostic.

## Next steps[​](#next-steps "Direct link to Next steps")

* [Configure validation rules](/docs/federation/how-to/configure-validation-rules.md)
* [Understand ownership and references](/docs/federation/explanation/ownership-and-references.md)
* [Troubleshoot local source errors](/docs/federation/reference/troubleshooting.md#filesystem-source-errors)