N8n:create Community Node Lint Rule

Create Community Node Lint Rule

Guide for adding new ESLint rules to packages/@n8n/eslint-plugin-community-nodes/.

All paths below are relative to packages/@n8n/eslint-plugin-community-nodes/.

Step 1: Understand the Rule

Before writing code, clarify:

What does the rule detect? (missing property, wrong pattern, bad value)
Where does it apply? (.node.ts files, credential classes, both)
Severity: error (must fix) or warn (should fix)?
Fixable? Can it be auto-fixed safely, or only suggest?
Scope: Both recommended configs, or exclude from recommendedWithoutN8nCloudSupport?

Step 2: Implement the Rule

Create src/rules/<rule-name>.ts:

import { AST_NODE_TYPES } from '@typescript-eslint/utils';

import {
  isNodeTypeClass,       // or isCredentialTypeClass
  findClassProperty,
  findObjectProperty,
  createRule,
} from '../utils/index.js';

Naming: Export as PascalCaseRule (e.g. MissingPairedItemRule). The name field is kebab-case.

Available AST helpers — see reference.md (opens in a new tab) for the full catalog of ast-utils and file-utils exports.

Step 3: Write Tests

Create src/rules/<rule-name>.test.ts:

import { RuleTester } from '@typescript-eslint/rule-tester';

import { YourRuleNameRule } from './rule-name.js';

const ruleTester = new RuleTester();

// Helper to generate test code — keeps test cases readable
function createNodeCode(

Test guidelines:

Always test that non-INodeType classes are skipped (valid case)
Test both the error message and the fixed output for fixable rules
For rules with options, test each option combination
For rules using filesystem, mock with vi.mock('../utils/file-utils.js')
For suggestion-only rules, use errors: [{ messageId, suggestions: [...] }]

Step 4: Register the Rule

4a. Add to `src/rules/index.ts`

import { YourRuleNameRule } from './rule-name.js';

// Add to the rules object:
export const rules = {
  // ... existing rules
  'rule-name': YourRuleNameRule,
} satisfies Record<string, AnyRuleModule>;

4b. Add to `src/plugin.ts` configs

Add to both config objects (unless the rule depends on n8n cloud features):

'@n8n/community-nodes/rule-name': 'error',  // or 'warn'

Use error for rules that catch bugs or required patterns
Use warn for style/convention rules (like options-sorted-alphabetically)
If the rule uses no-restricted-globals or no-restricted-imports patterns, only add to recommended (not recommendedWithoutN8nCloudSupport)

Step 5: Write Documentation

Create docs/rules/<rule-name>.md:

# Description of what the rule does (`@n8n/community-nodes/rule-name`)

<!-- end auto-generated rule header -->

## Rule Details

Explain why this rule exists and what problem it prevents.

## Examples

### Incorrect

\`\`\`typescript
// code that triggers the rule
\`\`\`

### Correct

\`\`\`typescript
// code that passes the rule
\`\`\`

The header above  will be regenerated by pnpm build:docs. Write a reasonable first version — it gets overwritten.

Step 6: Verify

Run from packages/@n8n/eslint-plugin-community-nodes/:

pushd packages/@n8n/eslint-plugin-community-nodes
pnpm test <rule-name>.test.ts   # tests pass
pnpm typecheck                   # types are clean
pnpm build                       # compiles
pnpm build:docs                  # regenerates doc headers and README table
pnpm lint:docs                   # docs match schema
popd

Checklist

Not done: Rule file: src/rules/<rule-name>.ts
Not done: Test file: src/rules/<rule-name>.test.ts
Not done: Registered in src/rules/index.ts
Not done: Added to configs in src/plugin.ts
Not done: Doc file: docs/rules/<rule-name>.md
Not done: README table updated via pnpm build:docs
Not done: All verification commands pass