@n8n/eslint-plugin-community-nodes 0.9.0 → 0.11.0

package/docs/rules/cred-class-field-icon-missing.md

@@ -0,0 +1,47 @@
+# Credential class must have an `icon` property defined (`@n8n/community-nodes/cred-class-field-icon-missing`)
+
+💼 This rule is enabled in the following configs: ✅ `recommended`, ☑️ `recommendedWithoutN8nCloudSupport`.
+
+💡 This rule is manually fixable by [editor suggestions](https://eslint.org/docs/latest/use/core-concepts#rule-suggestions).
+
+<!-- end auto-generated rule header -->
+
+## Rule Details
+
+Validates that credential classes define an `icon` class field. Icons are required for credentials to display correctly in the n8n editor.
+
+## Examples
+
+### ❌ Incorrect
+
+```typescript
+export class MyServiceApi implements ICredentialType {
+  name = 'myServiceApi';
+  displayName = 'My Service API';
+  // Missing icon property
+
+  properties: INodeProperties[] = [];
+}
+```
+
+### ✅ Correct
+
+```typescript
+export class MyServiceApi implements ICredentialType {
+  name = 'myServiceApi';
+  displayName = 'My Service API';
+  icon = 'file:myService.svg' as const;
+
+  properties: INodeProperties[] = [];
+}
+```
+
+```typescript
+export class MyServiceApi implements ICredentialType {
+  name = 'myServiceApi';
+  displayName = 'My Service API';
+  icon = { light: 'file:myService.svg', dark: 'file:myService.dark.svg' } as const;
+
+  properties: INodeProperties[] = [];
+}
+```

package/docs/rules/node-class-description-icon-missing.md

@@ -0,0 +1,52 @@
+# Node class description must have an `icon` property defined (`@n8n/community-nodes/node-class-description-icon-missing`)
+
+💼 This rule is enabled in the following configs: ✅ `recommended`, ☑️ `recommendedWithoutN8nCloudSupport`.
+
+💡 This rule is manually fixable by [editor suggestions](https://eslint.org/docs/latest/use/core-concepts#rule-suggestions).
+
+<!-- end auto-generated rule header -->
+
+## Rule Details
+
+Validates that node classes define an `icon` property in their `description` object. Icons are required for nodes to display correctly in the n8n editor.
+
+## Examples
+
+### ❌ Incorrect
+
+```typescript
+export class MyNode implements INodeType {
+  description: INodeTypeDescription = {
+    displayName: 'My Node',
+    name: 'myNode',
+    // Missing icon property
+  };
+}
+```
+
+### ✅ Correct
+
+```typescript
+export class MyNode implements INodeType {
+  description: INodeTypeDescription = {
+    displayName: 'My Node',
+    name: 'myNode',
+    icon: 'file:myNode.svg',
+    // ...
+  };
+}
+```
+
+```typescript
+export class MyNode implements INodeType {
+  description: INodeTypeDescription = {
+    displayName: 'My Node',
+    name: 'myNode',
+    icon: {
+      light: 'file:myNode.svg',
+      dark: 'file:myNode.dark.svg',
+    },
+    // ...
+  };
+}
+```

package/docs/rules/node-connection-type-literal.md

@@ -0,0 +1,46 @@
+# Disallow string literals in node description `inputs`/`outputs` — use `NodeConnectionTypes` enum instead (`@n8n/community-nodes/node-connection-type-literal`)
+
+💼 This rule is enabled in the following configs: ✅ `recommended`, ☑️ `recommendedWithoutN8nCloudSupport`.
+
+🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
+
+<!-- end auto-generated rule header -->
+
+## Rule Details
+
+Using raw string literals like `'main'` in `inputs` and `outputs` is fragile: the values are not type-checked, and typos or renamed connection types will go undetected. The `NodeConnectionTypes` object from `n8n-workflow` is the single source of truth and should always be used instead.
+
+## Examples
+
+### ❌ Incorrect
+
+```typescript
+import type { INodeType, INodeTypeDescription } from 'n8n-workflow';
+
+export class MyNode implements INodeType {
+  description: INodeTypeDescription = {
+    displayName: 'My Node',
+    name: 'myNode',
+    inputs: ['main'],
+    outputs: ['main'],
+    properties: [],
+  };
+}
+```
+
+### ✅ Correct
+
+```typescript
+import type { INodeType, INodeTypeDescription } from 'n8n-workflow';
+import { NodeConnectionTypes } from 'n8n-workflow';
+
+export class MyNode implements INodeType {
+  description: INodeTypeDescription = {
+    displayName: 'My Node',
+    name: 'myNode',
+    inputs: [NodeConnectionTypes.Main],
+    outputs: [NodeConnectionTypes.Main],
+    properties: [],
+  };
+}
+```

package/docs/rules/options-sorted-alphabetically.md

@@ -0,0 +1,63 @@
+# Enforce alphabetical ordering of options arrays in n8n node properties (`@n8n/community-nodes/options-sorted-alphabetically`)
+
+⚠️ This rule _warns_ in the following configs: ✅ `recommended`, ☑️ `recommendedWithoutN8nCloudSupport`.
+
+<!-- end auto-generated rule header -->
+
+## Rule Details
+
+Warns when an `options`-type parameter has its options array not sorted alphabetically by name. Applies to all `type: 'options'` parameters — including `resource`, `operation`, and any other dropdowns.
+
+Alphabetical ordering is an [official n8n UI design requirement](https://docs.n8n.io/integrations/creating-nodes/plan/node-ui-design/#lists) and the most frequently flagged issue in community node reviews.
+
+Comparison is case-insensitive and locale-aware (handles non-ASCII names such as Spanish or Portuguese labels).
+
+## Examples
+
+### ❌ Incorrect
+
+```typescript
+export class MyNode implements INodeType {
+  description: INodeTypeDescription = {
+    displayName: 'My Service',
+    name: 'myService',
+    properties: [
+      {
+        displayName: 'Resource',
+        name: 'resource',
+        type: 'options',
+        options: [
+          { name: 'User', value: 'user' },
+          { name: 'Contact', value: 'contact' }, // out of order
+          { name: 'Project', value: 'project' },
+        ],
+        default: 'user',
+      },
+    ],
+  };
+}
+```
+
+### ✅ Correct
+
+```typescript
+export class MyNode implements INodeType {
+  description: INodeTypeDescription = {
+    displayName: 'My Service',
+    name: 'myService',
+    properties: [
+      {
+        displayName: 'Resource',
+        name: 'resource',
+        type: 'options',
+        options: [
+          { name: 'Contact', value: 'contact' },
+          { name: 'Project', value: 'project' },
+          { name: 'User', value: 'user' },
+        ],
+        default: 'contact',
+      },
+    ],
+  };
+}
+```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@n8n/eslint-plugin-community-nodes",
   "type": "module",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "main": "./dist/plugin.js",
   "types": "./dist/plugin.d.ts",
   "exports": {
@@ -15,17 +15,20 @@
     "fastest-levenshtein": "1.0.16"
   },
   "devDependencies": {
+    "@types/node": "24.10.1",
     "@typescript-eslint/rule-tester": "^8.35.0",
     "eslint-doc-generator": "^2.2.2",
     "eslint-plugin-eslint-plugin": "^7.0.0",
     "rimraf": "6.0.1",
-    "typescript": "5.9.2",
-    "vitest": "^3.1.3",
-    "@n8n/typescript-config": "1.3.0",
-    "@n8n/vitest-config": "1.7.0"
+    "typescript": "6.0.2",
+    "vitest": "^4.1.1",
+    "@n8n/typescript-config": "1.4.0",
+    "@n8n/vitest-config": "1.9.0",
+    "n8n-workflow": "2.16.0"
   },
   "peerDependencies": {
-    "eslint": ">= 9"
+    "eslint": ">= 9",
+    "n8n-workflow": ">=2"
   },
   "eslint-doc-generator": {
     "configEmoji": [

package/src/plugin.ts

@@ -31,8 +31,12 @@ const configs = {
 			'@n8n/community-nodes/no-credential-reuse': 'error',
 			'@n8n/community-nodes/no-http-request-with-manual-auth': 'error',
 			'@n8n/community-nodes/icon-validation': 'error',
+			'@n8n/community-nodes/options-sorted-alphabetically': 'warn',
 			'@n8n/community-nodes/resource-operation-pattern': 'warn',
 			'@n8n/community-nodes/credential-documentation-url': 'error',
+			'@n8n/community-nodes/node-class-description-icon-missing': 'error',
+			'@n8n/community-nodes/cred-class-field-icon-missing': 'error',
+			'@n8n/community-nodes/node-connection-type-literal': 'error',
 		},
 	},
 	recommendedWithoutN8nCloudSupport: {
@@ -50,8 +54,12 @@ const configs = {
 			'@n8n/community-nodes/no-credential-reuse': 'error',
 			'@n8n/community-nodes/no-http-request-with-manual-auth': 'error',
 			'@n8n/community-nodes/icon-validation': 'error',
+			'@n8n/community-nodes/options-sorted-alphabetically': 'warn',
 			'@n8n/community-nodes/credential-documentation-url': 'error',
 			'@n8n/community-nodes/resource-operation-pattern': 'warn',
+			'@n8n/community-nodes/node-class-description-icon-missing': 'error',
+			'@n8n/community-nodes/cred-class-field-icon-missing': 'error',
+			'@n8n/community-nodes/node-connection-type-literal': 'error',
 		},
 	},
 } satisfies Record<string, Linter.Config>;

package/src/rules/cred-class-field-icon-missing.test.ts

@@ -0,0 +1,96 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+
+import { CredClassFieldIconMissingRule } from './cred-class-field-icon-missing.js';
+
+const ruleTester = new RuleTester();
+
+const credFilePath = '/tmp/TestCredential.credentials.ts';
+const nonCredFilePath = '/tmp/SomeHelper.ts';
+
+function createCredentialCode(withIcon: boolean): string {
+	const iconLine = withIcon ? "\n\ticon = 'file:testCredential.svg' as const;" : '';
+	return `
+import type { ICredentialType, INodeProperties } from 'n8n-workflow';
+
+export class TestCredential implements ICredentialType {
+	name = 'testApi';
+	displayName = 'Test API';
+	documentationUrl = 'https://docs.example.com';${iconLine}
+
+	properties: INodeProperties[] = [];
+}`;
+}
+
+function createCredentialWithLightDarkIcon(): string {
+	return `
+import type { ICredentialType, INodeProperties } from 'n8n-workflow';
+
+export class TestCredential implements ICredentialType {
+	name = 'testApi';
+	displayName = 'Test API';
+	icon = { light: 'file:testCredential.svg', dark: 'file:testCredential.dark.svg' } as const;
+
+	properties: INodeProperties[] = [];
+}`;
+}
+
+function createRegularClass(): string {
+	return `
+export class RegularClass {
+	name = 'test';
+}`;
+}
+
+ruleTester.run('cred-class-field-icon-missing', CredClassFieldIconMissingRule, {
+	valid: [
+		{
+			name: 'credential with icon defined',
+			filename: credFilePath,
+			code: createCredentialCode(true),
+		},
+		{
+			name: 'credential with light/dark icon object',
+			filename: credFilePath,
+			code: createCredentialWithLightDarkIcon(),
+		},
+		{
+			name: 'class not implementing ICredentialType is ignored',
+			filename: credFilePath,
+			code: createRegularClass(),
+		},
+		{
+			name: 'non-.credentials.ts file is ignored',
+			filename: nonCredFilePath,
+			code: createCredentialCode(false),
+		},
+	],
+	invalid: [
+		{
+			name: 'credential missing icon property',
+			filename: credFilePath,
+			code: createCredentialCode(false),
+			errors: [
+				{
+					messageId: 'missingIcon',
+					suggestions: [
+						{
+							messageId: 'addPlaceholder',
+							output: `
+import type { ICredentialType, INodeProperties } from 'n8n-workflow';
+
+export class TestCredential implements ICredentialType {
+	name = 'testApi';
+	displayName = 'Test API';
+	documentationUrl = 'https://docs.example.com';
+
+	properties: INodeProperties[] = [];
+
+	icon = "file:./icon.svg";
+}`,
+						},
+					],
+				},
+			],
+		},
+	],
+});

package/src/rules/cred-class-field-icon-missing.ts

@@ -0,0 +1,59 @@
+import {
+	isCredentialTypeClass,
+	findClassProperty,
+	isFileType,
+	createRule,
+} from '../utils/index.js';
+
+export const CredClassFieldIconMissingRule = createRule({
+	name: 'cred-class-field-icon-missing',
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Credential class must have an `icon` property defined',
+		},
+		messages: {
+			missingIcon: 'Credential class is missing required `icon` property',
+			addPlaceholder: 'Add icon property with placeholder',
+		},
+		schema: [],
+		hasSuggestions: true,
+	},
+	defaultOptions: [],
+	create(context) {
+		if (!isFileType(context.filename, '.credentials.ts')) {
+			return {};
+		}
+
+		return {
+			ClassDeclaration(node) {
+				if (!isCredentialTypeClass(node)) {
+					return;
+				}
+
+				const iconProperty = findClassProperty(node, 'icon');
+				if (iconProperty?.value) {
+					return;
+				}
+
+				context.report({
+					node,
+					messageId: 'missingIcon',
+					suggest: [
+						{
+							messageId: 'addPlaceholder',
+							fix(fixer) {
+								const classBody = node.body.body;
+								const lastProperty = classBody[classBody.length - 1];
+								if (lastProperty) {
+									return fixer.insertTextAfter(lastProperty, '\n\n\ticon = "file:./icon.svg";');
+								}
+								return null;
+							},
+						},
+					],
+				});
+			},
+		};
+	},
+});

package/src/rules/index.ts

@@ -1,6 +1,7 @@
 import type { AnyRuleModule } from '@typescript-eslint/utils/ts-eslint';
 
 import { AiNodePackageJsonRule } from './ai-node-package-json.js';
+import { CredClassFieldIconMissingRule } from './cred-class-field-icon-missing.js';
 import { CredentialDocumentationUrlRule } from './credential-documentation-url.js';
 import { CredentialPasswordFieldRule } from './credential-password-field.js';
 import { CredentialTestRequiredRule } from './credential-test-required.js';
@@ -10,7 +11,10 @@ import { NoDeprecatedWorkflowFunctionsRule } from './no-deprecated-workflow-func
 import { NoHttpRequestWithManualAuthRule } from './no-http-request-with-manual-auth.js';
 import { NoRestrictedGlobalsRule } from './no-restricted-globals.js';
 import { NoRestrictedImportsRule } from './no-restricted-imports.js';
+import { NodeClassDescriptionIconMissingRule } from './node-class-description-icon-missing.js';
+import { NodeConnectionTypeLiteralRule } from './node-connection-type-literal.js';
 import { NodeUsableAsToolRule } from './node-usable-as-tool.js';
+import { OptionsSortedAlphabeticallyRule } from './options-sorted-alphabetically.js';
 import { PackageNameConventionRule } from './package-name-convention.js';
 import { ResourceOperationPatternRule } from './resource-operation-pattern.js';
 
@@ -21,6 +25,7 @@ export const rules = {
 	'credential-password-field': CredentialPasswordFieldRule,
 	'no-deprecated-workflow-functions': NoDeprecatedWorkflowFunctionsRule,
 	'node-usable-as-tool': NodeUsableAsToolRule,
+	'options-sorted-alphabetically': OptionsSortedAlphabeticallyRule,
 	'package-name-convention': PackageNameConventionRule,
 	'credential-test-required': CredentialTestRequiredRule,
 	'no-credential-reuse': NoCredentialReuseRule,
@@ -28,4 +33,7 @@ export const rules = {
 	'icon-validation': IconValidationRule,
 	'resource-operation-pattern': ResourceOperationPatternRule,
 	'credential-documentation-url': CredentialDocumentationUrlRule,
+	'node-class-description-icon-missing': NodeClassDescriptionIconMissingRule,
+	'cred-class-field-icon-missing': CredClassFieldIconMissingRule,
+	'node-connection-type-literal': NodeConnectionTypeLiteralRule,
 } satisfies Record<string, AnyRuleModule>;

package/src/rules/node-class-description-icon-missing.test.ts

@@ -0,0 +1,113 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+
+import { NodeClassDescriptionIconMissingRule } from './node-class-description-icon-missing.js';
+
+const ruleTester = new RuleTester();
+
+const nodeFilePath = '/tmp/TestNode.node.ts';
+const nonNodeFilePath = '/tmp/SomeHelper.ts';
+
+function createNodeCode(withIcon: boolean): string {
+	const iconLine = withIcon ? "\n\t\ticon: 'file:testNode.svg'," : '';
+	return `
+import type { INodeType } from 'n8n-workflow';
+
+export class TestNode implements INodeType {
+	description = {
+		displayName: 'Test Node',
+		name: 'testNode',
+		group: ['transform'],
+		version: 1,
+		description: 'Test',${iconLine}
+		inputs: ['main'],
+		outputs: ['main'],
+		properties: [],
+	};
+}`;
+}
+
+function createNodeCodeWithLightDarkIcon(): string {
+	return `
+import type { INodeType } from 'n8n-workflow';
+
+export class TestNode implements INodeType {
+	description = {
+		displayName: 'Test Node',
+		name: 'testNode',
+		group: ['transform'],
+		version: 1,
+		description: 'Test',
+		icon: { light: 'file:testNode.svg', dark: 'file:testNode.dark.svg' },
+		inputs: ['main'],
+		outputs: ['main'],
+		properties: [],
+	};
+}`;
+}
+
+function createRegularClass(): string {
+	return `
+export class RegularClass {
+	description = {
+		displayName: 'Test',
+	};
+}`;
+}
+
+ruleTester.run('node-class-description-icon-missing', NodeClassDescriptionIconMissingRule, {
+	valid: [
+		{
+			name: 'node with icon defined',
+			filename: nodeFilePath,
+			code: createNodeCode(true),
+		},
+		{
+			name: 'node with light/dark icon object',
+			filename: nodeFilePath,
+			code: createNodeCodeWithLightDarkIcon(),
+		},
+		{
+			name: 'class not implementing INodeType is ignored',
+			filename: nodeFilePath,
+			code: createRegularClass(),
+		},
+		{
+			name: 'non-.node.ts file is ignored',
+			filename: nonNodeFilePath,
+			code: createNodeCode(false),
+		},
+	],
+	invalid: [
+		{
+			name: 'node missing icon property',
+			filename: nodeFilePath,
+			code: createNodeCode(false),
+			errors: [
+				{
+					messageId: 'missingIcon',
+					suggestions: [
+						{
+							messageId: 'addPlaceholder',
+							output: `
+import type { INodeType } from 'n8n-workflow';
+
+export class TestNode implements INodeType {
+	description = {
+		displayName: 'Test Node',
+		name: 'testNode',
+		group: ['transform'],
+		version: 1,
+		description: 'Test',
+		inputs: ['main'],
+		outputs: ['main'],
+		properties: [],
+		icon: "file:./icon.svg",
+	};
+}`,
+						},
+					],
+				},
+			],
+		},
+	],
+});

package/src/rules/node-class-description-icon-missing.ts

@@ -0,0 +1,71 @@
+import { TSESTree } from '@typescript-eslint/utils';
+
+import {
+	isNodeTypeClass,
+	findClassProperty,
+	findObjectProperty,
+	isFileType,
+	createRule,
+} from '../utils/index.js';
+
+export const NodeClassDescriptionIconMissingRule = createRule({
+	name: 'node-class-description-icon-missing',
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Node class description must have an `icon` property defined',
+		},
+		messages: {
+			missingIcon: 'Node class description is missing required `icon` property',
+			addPlaceholder: 'Add icon property with placeholder',
+		},
+		schema: [],
+		hasSuggestions: true,
+	},
+	defaultOptions: [],
+	create(context) {
+		if (!isFileType(context.filename, '.node.ts')) {
+			return {};
+		}
+
+		return {
+			ClassDeclaration(node) {
+				if (!isNodeTypeClass(node)) {
+					return;
+				}
+
+				const descriptionProperty = findClassProperty(node, 'description');
+				if (
+					!descriptionProperty?.value ||
+					descriptionProperty.value.type !== TSESTree.AST_NODE_TYPES.ObjectExpression
+				) {
+					return;
+				}
+
+				const descriptionValue = descriptionProperty.value;
+				const iconProperty = findObjectProperty(descriptionValue, 'icon');
+				if (iconProperty) {
+					return;
+				}
+
+				context.report({
+					node,
+					messageId: 'missingIcon',
+					suggest: [
+						{
+							messageId: 'addPlaceholder',
+							fix(fixer) {
+								const lastProperty =
+									descriptionValue.properties[descriptionValue.properties.length - 1];
+								if (lastProperty) {
+									return fixer.insertTextAfter(lastProperty, ',\n\t\ticon: "file:./icon.svg"');
+								}
+								return null;
+							},
+						},
+					],
+				});
+			},
+		};
+	},
+});