# Set up the linter Copy as Markdown[View as Markdown](/docs/development/developer-tools/eventcatalog-linter/setup.md) *** This guide takes you from a fresh catalog to a linted, CI-checked one: run the linter, read what it reports, fix a problem, create a configuration file, and add a pull-request check. It takes about ten minutes. ## What you need[​](#what-you-need "Direct link to What you need") * An EventCatalog project. If you don't have one, `npx @eventcatalog/create-eventcatalog@latest my-catalog` creates one with example content. * Node.js 18 or later. ## 1. Run the linter[​](#1-run-the-linter "Direct link to 1. Run the linter") From the root of your catalog (the folder containing `eventcatalog.config.js`): ``` npx @eventcatalog/linter ``` You don't need to install anything first. The linter scans your `domains/`, `services/`, `events/` and other resource folders, validates every file, and prints what it found: ``` ✔ No problems found! 178 files checked ``` If your catalog is already clean, congratulations — skip to [step 4](#4-create-a-configuration-file) to see how to customise it. Otherwise, keep reading. ## 2. Read the output[​](#2-read-the-output "Direct link to 2. Read the output") Let's introduce a couple of mistakes on purpose so there is something to look at. Open any service — for example `services/order-service/index.mdx` — and change `owners:` to `owner:`, then misspell one of the events it sends: services/order-service/index.mdx ``` --- id: order-service name: Order Service version: 1.0.0 summary: Handles orders owner: - platform-team sends: - id: OrderCreatd --- ``` Run the linter again: ``` services/order-service/index.mdx 2:1 ✖ error At least one owner is required [owners] (best-practices/owner-required) 6:1 ✖ error Unknown property "owner". Did you mean "owners"? [owner] (schema/unknown-field) 9:5 ✖ error Referenced event/command/query "OrderCreatd" does not exist. Did you mean "OrderCreated"? [sends[0]] (refs/resource-exists) ✖ 3 problems (3 errors, 0 warnings) in 1 file 178 files checked ``` Each line has the same shape: | Part | Meaning | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ | | `6:1` | Line and column in the file. Most terminals let you click `path:line:col`. | | `✖ error` / `⚠ warning` | Severity. Errors fail the run; warnings don't unless you ask them to. | | The message | What is wrong, and a suggestion when the linter can work one out. | | `[owner]` | The frontmatter field the finding is about. | | `(schema/unknown-field)` | The rule that produced it — look it up in the [rules reference](/docs/development/developer-tools/eventcatalog-linter/reference/rules.md). | Notice that one typo produced two findings: `owner` is unknown **and** `owners` is missing. That's expected — fixing the typo clears both. ## 3. Fix the problems[​](#3-fix-the-problems "Direct link to 3. Fix the problems") Change `owner` back to `owners` and `OrderCreatd` to `OrderCreated`, then re-run. You should be back to `✔ No problems found!`. That loop — run, read, fix — is how you'll use the linter day to day. Because the message includes the line number and a suggestion, most fixes are a single edit. The [fix common problems](/docs/development/developer-tools/eventcatalog-linter/how-to/fix-common-problems.md) guide covers the messages you're most likely to meet. ## 4. Create a configuration file[​](#4-create-a-configuration-file "Direct link to 4. Create a configuration file") Defaults are sensible, but every team has its own standards. Let the linter write a starting point for you: ``` npx @eventcatalog/linter --init ``` ``` ✔ Created .eventcatalogrc.js 178 catalog files found, CommonJS config written ``` Open `.eventcatalogrc.js`. Every rule is listed with a one-line description and its default severity: .eventcatalogrc.js ``` module.exports = { rules: { // Best practices // Resources have a summary 'best-practices/summary-required': 'error', // Resources have at least one owner 'best-practices/owner-required': 'error', // Resources have markdown body content beyond the frontmatter 'best-practices/description-required': 'warn', // ... }, ignorePatterns: [], overrides: [], }; ``` Try changing one rule. Perhaps your team doesn't want body content to be a warning yet: ``` 'best-practices/description-required': 'off', ``` Run the linter again and the warning is gone. The three values are `'error'`, `'warn'` and `'off'`; the [configure rules guide](/docs/development/developer-tools/eventcatalog-linter/how-to/configure-rules.md) covers options, ignore patterns and per-folder overrides. ## 5. Add the check to your pipeline[​](#5-add-the-check-to-your-pipeline "Direct link to 5. Add the check to your pipeline") The linter exits with code `1` when it finds errors, which is all a CI system needs. For GitHub Actions: .github/workflows/lint-catalog.yml ``` name: Lint catalog on: [pull_request] jobs: lint: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 20 - run: npx @eventcatalog/linter --max-warnings 0 ``` `--max-warnings 0` makes warnings fail the build too. If you'd rather let warnings through, drop the flag. In CI the linter automatically keeps its progress spinner out of the logs, so you only see findings. See [Run in CI](/docs/development/developer-tools/eventcatalog-linter/how-to/run-in-ci.md) for GitLab and other pipelines. ## Next steps[​](#next-steps "Direct link to Next steps") * [Configure rules](/docs/development/developer-tools/eventcatalog-linter/how-to/configure-rules.md) for your team's standards, including per-folder overrides. * [Reference resources from other catalogs](/docs/development/developer-tools/eventcatalog-linter/how-to/reference-external-catalogs.md) if your services consume events documented elsewhere. * Browse the [rules reference](/docs/development/developer-tools/eventcatalog-linter/reference/rules.md) to see everything the linter can catch.