@n8n/eslint-plugin-community-nodes 0.3.0 → 0.5.0

package/docs/rules/no-restricted-globals.md

@@ -0,0 +1,44 @@
+# Disallow usage of restricted global variables in community nodes (`@n8n/community-nodes/no-restricted-globals`)
+
+💼 This rule is enabled in the ✅ `recommended` config.
+
+<!-- end auto-generated rule header -->
+
+## Rule Details
+
+Prevents the use of Node.js global variables that are not allowed in n8n Cloud. While these globals may be available in self-hosted environments, they are restricted on n8n Cloud for security and stability reasons.
+
+Restricted globals include: `clearInterval`, `clearTimeout`, `global`, `globalThis`, `process`, `setInterval`, `setTimeout`, `setImmediate`, `clearImmediate`, `__dirname`, `__filename`.
+
+## Examples
+
+### ❌ Incorrect
+
+```typescript
+export class MyNode implements INodeType {
+  async execute(this: IExecuteFunctions) {
+    // These globals are not allowed on n8n Cloud
+    const pid = process.pid;
+    const dir = __dirname;
+
+    setTimeout(() => {
+      console.log('This will not work on n8n Cloud');
+    }, 1000);
+
+    return this.prepareOutputData([]);
+  }
+}
+```
+
+### ✅ Correct
+
+```typescript
+export class MyNode implements INodeType {
+  async execute(this: IExecuteFunctions) {
+    // Use n8n context methods instead
+    const timezone = this.getTimezone();
+
+    return this.prepareOutputData([]);
+  }
+}
+```

package/docs/rules/no-restricted-imports.md

@@ -0,0 +1,47 @@
+# Disallow usage of restricted imports in community nodes (`@n8n/community-nodes/no-restricted-imports`)
+
+💼 This rule is enabled in the ✅ `recommended` config.
+
+<!-- end auto-generated rule header -->
+
+## Rule Details
+
+Prevents importing external dependencies that are not allowed on n8n Cloud. Community nodes running on n8n Cloud are restricted to a specific set of allowed modules for security and performance reasons.
+
+**Allowed modules:** `n8n-workflow`, `lodash`, `moment`, `p-limit`, `luxon`, `zod`, `crypto`, `node:crypto`
+
+Relative imports (starting with `./` or `../`) are always allowed.
+
+## Examples
+
+### ❌ Incorrect
+
+```typescript
+import axios from 'axios'; // External dependency not allowed
+import { readFile } from 'fs'; // Node.js modules not in allowlist
+const request = require('request'); // Same applies to require()
+
+// Dynamic imports are also restricted
+const module = await import('some-package');
+```
+
+### ✅ Correct
+
+```typescript
+import { IExecuteFunctions, INodeType } from 'n8n-workflow'; // Allowed
+import { get } from 'lodash'; // Allowed
+import moment from 'moment'; // Allowed
+import { DateTime } from 'luxon'; // Allowed
+import { createHash } from 'crypto'; // Allowed
+
+import { MyHelper } from './helpers/MyHelper'; // Relative imports allowed
+import config from '../config'; // Relative imports allowed
+
+export class MyNode implements INodeType {
+  // ... implementation
+}
+```
+
+## When This Rule Doesn't Apply
+
+This rule only applies to community nodes intended for n8n Cloud. If you're building nodes exclusively for self-hosted environments, you may disable this rule, but be aware that your package will not be compatible with n8n Cloud.

package/docs/rules/node-usable-as-tool.md

@@ -0,0 +1,43 @@
+# Ensure node classes have usableAsTool property (`@n8n/community-nodes/node-usable-as-tool`)
+
+💼 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
+
+Ensures your nodes declare whether they can be used as tools in AI workflows. This property helps n8n determine if your node is suitable for AI-assisted automation.
+
+## Examples
+
+### ❌ Incorrect
+
+```typescript
+export class MyNode implements INodeType {
+  description: INodeTypeDescription = {
+    displayName: 'My Node',
+    name: 'myNode',
+    group: ['input'],
+    version: 1,
+    // Missing usableAsTool property
+    properties: [],
+  };
+}
+```
+
+### ✅ Correct
+
+```typescript
+export class MyNode implements INodeType {
+  description: INodeTypeDescription = {
+    displayName: 'My Node',
+    name: 'myNode',
+    group: ['input'],
+    version: 1,
+    usableAsTool: true,
+    properties: [],
+  };
+}
+```

package/docs/rules/package-name-convention.md

@@ -0,0 +1,52 @@
+# Enforce correct package naming convention for n8n community nodes (`@n8n/community-nodes/package-name-convention`)
+
+💼 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 your package name follows the correct n8n community node naming convention. Package names must start with `n8n-nodes-` and can optionally be scoped.
+
+## Examples
+
+### ❌ Incorrect
+
+```json
+{
+  "name": "my-service-integration"
+}
+```
+
+```json
+{
+  "name": "nodes-my-service"
+}
+```
+
+```json
+{
+  "name": "@company/my-service"
+}
+```
+
+### ✅ Correct
+
+```json
+{
+  "name": "n8n-nodes-my-service"
+}
+```
+
+```json
+{
+  "name": "@company/n8n-nodes-my-service"
+}
+```
+
+## Best Practices
+
+- Use descriptive service names: `n8n-nodes-github` rather than `n8n-nodes-api`
+- For company packages, use your organization scope: `@mycompany/n8n-nodes-internal-tool`

package/docs/rules/resource-operation-pattern.md

@@ -0,0 +1,84 @@
+# Enforce proper resource/operation pattern for better UX in n8n nodes (`@n8n/community-nodes/resource-operation-pattern`)
+
+⚠️ This rule _warns_ in the following configs: ✅ `recommended`, ☑️ `recommendedWithoutN8nCloudSupport`.
+
+<!-- end auto-generated rule header -->
+
+## Rule Details
+
+Warns when a node has more than 5 operations without organizing them into resources. The resource/operation pattern improves user experience by grouping related operations together, making complex nodes easier to navigate.
+
+When you have many operations, users benefit from having them organized into logical resource groups (e.g., "User", "Project", "File") rather than seeing a long flat list of operations.
+
+## Examples
+
+### ❌ Incorrect
+
+```typescript
+export class MyNode implements INodeType {
+  description: INodeTypeDescription = {
+    displayName: 'My Service',
+    name: 'myService',
+    properties: [
+      {
+        displayName: 'Operation',
+        name: 'operation',
+        type: 'options',
+        options: [
+          { name: 'Get User', value: 'getUser' },
+          { name: 'Create User', value: 'createUser' },
+          { name: 'Update User', value: 'updateUser' },
+          { name: 'Delete User', value: 'deleteUser' },
+          { name: 'Get Project', value: 'getProject' },
+          { name: 'Create Project', value: 'createProject' },
+          { name: 'List Files', value: 'listFiles' },
+          // 7+ operations without resources - hard to navigate!
+        ],
+      },
+      // ... other properties
+    ],
+  };
+}
+```
+
+### ✅ Correct
+
+```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: 'Project', value: 'project' },
+          { name: 'File', value: 'file' },
+        ],
+        default: 'user',
+      },
+      {
+        displayName: 'Operation',
+        name: 'operation',
+        type: 'options',
+        displayOptions: {
+          show: {
+            resource: ['user'],
+          },
+        },
+        options: [
+          { name: 'Get', value: 'get' },
+          { name: 'Create', value: 'create' },
+          { name: 'Update', value: 'update' },
+          { name: 'Delete', value: 'delete' },
+        ],
+        default: 'get',
+      },
+      // ... similar operation blocks for 'project' and 'file' resources
+    ],
+  };
+}
+```

package/eslint.config.mjs

@@ -0,0 +1,27 @@
+import { defineConfig } from 'eslint/config';
+import { nodeConfig } from '@n8n/eslint-config/node';
+import eslintPlugin from 'eslint-plugin-eslint-plugin';
+
+export default defineConfig([
+	nodeConfig,
+	eslintPlugin.configs.recommended,
+	{
+		files: ['src/**/*.ts'],
+		languageOptions: {
+			parserOptions: {
+				project: './tsconfig.json',
+				allowDefaultProject: true,
+			},
+		},
+		rules: {
+			// We use RuleCreator which adds this automatically
+			'eslint-plugin/require-meta-docs-url': 'off',
+			// typescript-eslint uses different pattern
+			'eslint-plugin/require-meta-default-options': 'off',
+			// Disable naming convention for plugin configs (ESLint rule names use kebab-case)
+			'@typescript-eslint/naming-convention': 'off',
+			// Allow default exports for ESLint plugin
+			'import-x/no-default-export': 'off',
+		},
+	},
+]);

package/package.json

@@ -1,7 +1,9 @@
 {
   "name": "@n8n/eslint-plugin-community-nodes",
   "type": "module",
-  "version": "0.3.0",
+  "version": "0.5.0",
+  "main": "./dist/plugin.js",
+  "types": "./dist/plugin.d.ts",
   "exports": {
     ".": {
       "types": "./dist/plugin.d.ts",
@@ -9,10 +11,13 @@
     }
   },
   "dependencies": {
-    "@typescript-eslint/utils": "^8.35.0"
+    "@typescript-eslint/utils": "^8.35.0",
+    "fastest-levenshtein": "1.0.16"
   },
   "devDependencies": {
     "@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",
@@ -22,6 +27,18 @@
   "peerDependencies": {
     "eslint": ">= 9"
   },
+  "eslint-doc-generator": {
+    "configEmoji": [
+      [
+        "recommended",
+        "✅"
+      ],
+      [
+        "recommendedWithoutN8nCloudSupport",
+        "☑️"
+      ]
+    ]
+  },
   "license": "SEE LICENSE IN LICENSE.md",
   "homepage": "https://n8n.io",
   "author": {
@@ -33,14 +50,18 @@
     "url": "git+https://github.com/n8n-io/n8n.git"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "tsc --project tsconfig.build.json",
+    "build:docs": "eslint-doc-generator",
     "clean": "rimraf dist .turbo",
     "dev": "pnpm watch",
     "format": "biome format --write .",
     "format:check": "biome ci .",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "lint:docs": "eslint-doc-generator --check",
     "test": "vitest run",
     "test:dev": "vitest",
     "typecheck": "tsc --noEmit",
-    "watch": "tsc --watch"
+    "watch": "tsc --watch --project tsconfig.build.json"
   }
 }

package/src/plugin.ts

@@ -1,14 +1,13 @@
 import type { ESLint, Linter } from 'eslint';
-import { rules } from './rules/index.js';
-import fs from 'node:fs';
 
-const pkg = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+import pkg from '../package.json' with { type: 'json' };
+import { rules } from './rules/index.js';
 
 const plugin = {
 	meta: {
 		name: pkg.name,
 		version: pkg.version,
-		namespace: 'n8n-community-nodes',
+		namespace: '@n8n/community-nodes',
 	},
 	// @ts-expect-error Rules type does not match for typescript-eslint and eslint
 	rules: rules as ESLint.Plugin['rules'],
@@ -18,38 +17,43 @@ const configs = {
 	recommended: {
 		ignores: ['eslint.config.{js,mjs,ts,mts}'],
 		plugins: {
-			'n8n-community-nodes': plugin,
+			'@n8n/community-nodes': plugin,
 		},
 		rules: {
-			'n8n-community-nodes/no-restricted-globals': 'error',
-			'n8n-community-nodes/no-restricted-imports': 'error',
-			'n8n-community-nodes/credential-password-field': 'error',
-			'n8n-community-nodes/no-deprecated-workflow-functions': 'error',
-			'n8n-community-nodes/node-usable-as-tool': 'error',
-			'n8n-community-nodes/package-name-convention': 'error',
-			'n8n-community-nodes/credential-test-required': 'error',
-			'n8n-community-nodes/no-credential-reuse': 'error',
-			'n8n-community-nodes/icon-validation': 'error',
-			'n8n-community-nodes/resource-operation-pattern': 'warn',
+			'@n8n/community-nodes/no-restricted-globals': 'error',
+			'@n8n/community-nodes/no-restricted-imports': 'error',
+			'@n8n/community-nodes/credential-password-field': 'error',
+			'@n8n/community-nodes/no-deprecated-workflow-functions': 'error',
+			'@n8n/community-nodes/node-usable-as-tool': 'error',
+			'@n8n/community-nodes/package-name-convention': 'error',
+			'@n8n/community-nodes/credential-test-required': 'error',
+			'@n8n/community-nodes/no-credential-reuse': 'error',
+			'@n8n/community-nodes/icon-validation': 'error',
+			'@n8n/community-nodes/resource-operation-pattern': 'warn',
+			'@n8n/community-nodes/credential-documentation-url': 'error',
 		},
 	},
 	recommendedWithoutN8nCloudSupport: {
 		ignores: ['eslint.config.{js,mjs,ts,mts}'],
 		plugins: {
-			'n8n-community-nodes': plugin,
+			'@n8n/community-nodes': plugin,
 		},
 		rules: {
-			'n8n-community-nodes/credential-password-field': 'error',
-			'n8n-community-nodes/no-deprecated-workflow-functions': 'error',
-			'n8n-community-nodes/node-usable-as-tool': 'error',
-			'n8n-community-nodes/package-name-convention': 'error',
-			'n8n-community-nodes/credential-test-required': 'error',
-			'n8n-community-nodes/no-credential-reuse': 'error',
-			'n8n-community-nodes/icon-validation': 'error',
-			'n8n-community-nodes/resource-operation-pattern': 'warn',
+			'@n8n/community-nodes/credential-password-field': 'error',
+			'@n8n/community-nodes/no-deprecated-workflow-functions': 'error',
+			'@n8n/community-nodes/node-usable-as-tool': 'error',
+			'@n8n/community-nodes/package-name-convention': 'error',
+			'@n8n/community-nodes/credential-test-required': 'error',
+			'@n8n/community-nodes/no-credential-reuse': 'error',
+			'@n8n/community-nodes/icon-validation': 'error',
+			'@n8n/community-nodes/credential-documentation-url': 'error',
+			'@n8n/community-nodes/resource-operation-pattern': 'warn',
 		},
 	},
 } satisfies Record<string, Linter.Config>;
 
-export const n8nCommunityNodesPlugin = { ...plugin, configs } satisfies ESLint.Plugin;
-export default n8nCommunityNodesPlugin;
+const pluginWithConfigs = { ...plugin, configs } satisfies ESLint.Plugin;
+
+const n8nCommunityNodesPlugin = pluginWithConfigs;
+export default pluginWithConfigs;
+export { rules, configs, n8nCommunityNodesPlugin };