# @n8n/eslint-plugin-community-nodes ESLint plugin for linting n8n community node packages to ensure consistency and best practices. ## Install ```sh npm install --save-dev eslint @n8n/eslint-plugin-community-nodes ``` **Requires ESLint `>=9` and [flat config](https://eslint.org/docs/latest/use/configure/configuration-files) ## Usage See the [ESLint docs](https://eslint.org/docs/latest/use/configure/configuration-files) for more information about extending config files. ### Recommended config This plugin exports a `recommended` config that enforces good practices. ```js import { n8nCommunityNodesPlugin } from '@n8n/eslint-plugin-community-nodes'; export default [ // … n8nCommunityNodesPlugin.configs.recommended, { rules: { '@n8n/community-nodes/node-usable-as-tool': 'warn', }, }, ]; ``` ## Rules πŸ’Ό Configurations enabled in.\ ⚠️ Configurations set to warn in.\ βœ… Set in the `recommended` configuration.\ β˜‘οΈ Set in the `recommendedWithoutN8nCloudSupport` configuration.\ πŸ”§ Automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/user-guide/command-line-interface#--fix).\ πŸ’‘ Manually fixable by [editor suggestions](https://eslint.org/docs/latest/use/core-concepts#rule-suggestions).\ ❌ Deprecated. | NameΒ Β Β Β Β Β Β Β Β Β Β Β Β Β Β Β Β Β Β Β Β Β Β Β Β Β Β Β Β Β Β  | Description | πŸ’Ό | ⚠️ | πŸ”§ | πŸ’‘ | ❌ | | :--------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--- | :--- | :- | :- | :- | | [ai-node-package-json](docs/rules/ai-node-package-json.md) | Enforce consistency between n8n.aiNodeSdkVersion and ai-node-sdk peer dependency in community node packages | βœ… β˜‘οΈ | | | | | | [cred-class-field-icon-missing](docs/rules/cred-class-field-icon-missing.md) | Credential class must have an `icon` property defined | βœ… β˜‘οΈ | | | πŸ’‘ | | | [cred-class-oauth2-naming](docs/rules/cred-class-oauth2-naming.md) | OAuth2 credentials must include `OAuth2` in the class name, `name`, and `displayName` | βœ… β˜‘οΈ | | πŸ”§ | | | | [credential-documentation-url](docs/rules/credential-documentation-url.md) | Enforce valid credential documentationUrl format (URL or lowercase alphanumeric slug) | βœ… β˜‘οΈ | | πŸ”§ | | | | [credential-password-field](docs/rules/credential-password-field.md) | Ensure fields with sensitive names have typeOptions.password = true | βœ… β˜‘οΈ | | πŸ”§ | | | | [credential-test-required](docs/rules/credential-test-required.md) | Ensure credentials have a credential test | βœ… β˜‘οΈ | | | πŸ’‘ | | | [credential-unnecessary-password](docs/rules/credential-unnecessary-password.md) | Warn when a credential field with no sensitive name uses typeOptions.password = true | | βœ… β˜‘οΈ | | | | | [icon-prefer-themed-variants](docs/rules/icon-prefer-themed-variants.md) | Encourage node and credential icons to provide light/dark variants instead of a single icon file | | βœ… β˜‘οΈ | | | | | [icon-validation](docs/rules/icon-validation.md) | Validate node and credential icon files exist and use the file: protocol | βœ… β˜‘οΈ | | | πŸ’‘ | | | [missing-paired-item](docs/rules/missing-paired-item.md) | Require pairedItem on INodeExecutionData objects in execute() methods to preserve item linking. | βœ… β˜‘οΈ | | | | | | [n8n-object-validation](docs/rules/n8n-object-validation.md) | Validate the structure of the "n8n" object in community node package.json (required keys, types, and dist/ paths) | βœ… β˜‘οΈ | | | | | | [no-builder-hint-leakage](docs/rules/no-builder-hint-leakage.md) | Disallow wire-format expression syntax (={{...}}) and NodeConnectionType string literals in builderHint texts and AI-builder prompts. Use expr() and SDK-canonical references instead. | βœ… β˜‘οΈ | | | | | | [no-credential-reuse](docs/rules/no-credential-reuse.md) | Prevent credential re-use security issues by ensuring nodes only reference credentials from the same package | βœ… β˜‘οΈ | | | πŸ’‘ | | | [no-dangerous-functions](docs/rules/no-dangerous-functions.md) | Disallow `eval`, the `Function` constructor, and `child_process` process-spawning functions (`exec`, `spawn`, etc.) in community nodes. | βœ… β˜‘οΈ | | | | | | [no-dead-files](docs/rules/no-dead-files.md) | Disallow leftover backup, editor, and test-artifact files in the `nodes/` and `credentials/` directories of a community node package | | βœ… β˜‘οΈ | | | | | [no-deprecated-workflow-functions](docs/rules/no-deprecated-workflow-functions.md) | Disallow usage of deprecated functions and types from n8n-workflow package | βœ… β˜‘οΈ | | | πŸ’‘ | | | [no-emoji-in-options](docs/rules/no-emoji-in-options.md) | Disallow emoji characters in node option name and displayName values | βœ… β˜‘οΈ | | | | | | [no-forbidden-lifecycle-scripts](docs/rules/no-forbidden-lifecycle-scripts.md) | Ban lifecycle scripts (prepare, preinstall, postinstall, etc.) in community node packages | βœ… β˜‘οΈ | | | | | | [no-hardcoded-secrets](docs/rules/no-hardcoded-secrets.md) | Disallow hardcoded secrets (API keys, tokens, passwords) embedded as string literals in source. | βœ… β˜‘οΈ | | | | | | [no-http-request-with-manual-auth](docs/rules/no-http-request-with-manual-auth.md) | Disallow this.helpers.httpRequest() in functions that call this.getCredentials(). Use this.helpers.httpRequestWithAuthentication() instead. | βœ… β˜‘οΈ | | | | | | [no-overrides-field](docs/rules/no-overrides-field.md) | Ban the "overrides" field in community node package.json | βœ… β˜‘οΈ | | | | | | [no-restricted-globals](docs/rules/no-restricted-globals.md) | Disallow usage of restricted global variables in community nodes. | βœ… | | | | | | [no-restricted-imports](docs/rules/no-restricted-imports.md) | Disallow usage of restricted imports in community nodes. | βœ… | | | | | | [no-runtime-dependencies](docs/rules/no-runtime-dependencies.md) | Disallow non-empty "dependencies" in community node package.json | βœ… β˜‘οΈ | | | | | | [no-silent-error-swallowing](docs/rules/no-silent-error-swallowing.md) | Disallow webhook lifecycle methods (checkExists, create, delete) from silently swallowing errors in catch blocks | βœ… β˜‘οΈ | | | | | | [no-template-placeholders](docs/rules/no-template-placeholders.md) | Disallow unresolved template placeholders in package.json | βœ… β˜‘οΈ | | | | | | [no-unsafe-connection-type-cast](docs/rules/no-unsafe-connection-type-cast.md) | Disallow type-erasing casts (`as never`, `as any`, `as unknown`) on node description `inputs`/`outputs` | βœ… β˜‘οΈ | | | πŸ’‘ | | | [node-class-description-icon-missing](docs/rules/node-class-description-icon-missing.md) | Node class description must have an `icon` property defined. Deprecated: use `require-node-description-fields` instead. | | | | πŸ’‘ | ❌ | | [node-connection-type-literal](docs/rules/node-connection-type-literal.md) | Disallow string literals in node description `inputs`/`outputs` β€” use `NodeConnectionTypes` enum instead | βœ… β˜‘οΈ | | πŸ”§ | | | | [node-registration-complete](docs/rules/node-registration-complete.md) | Ensure every `.node.ts` file in the `nodes/` directory is registered in the "n8n.nodes" array of package.json | | βœ… β˜‘οΈ | | | | | [node-usable-as-tool](docs/rules/node-usable-as-tool.md) | Ensure node classes have usableAsTool property | βœ… β˜‘οΈ | | πŸ”§ | | | | [open-ended-node-fields](docs/rules/open-ended-node-fields.md) | Discourage optional open-ended JSON fields in node properties | | βœ… β˜‘οΈ | | | | | [package-name-convention](docs/rules/package-name-convention.md) | Enforce correct package naming convention for n8n community nodes | βœ… β˜‘οΈ | | | πŸ’‘ | | | [require-files-array](docs/rules/require-files-array.md) | Require a non-empty "files" array in package.json | | βœ… β˜‘οΈ | | | | | [require-homepage](docs/rules/require-homepage.md) | Require a "homepage" field with a valid URL in package.json | | βœ… β˜‘οΈ | | | | | [require-node-api-error](docs/rules/require-node-api-error.md) | Require NodeApiError or NodeOperationError for error wrapping in catch blocks. Raw errors lose HTTP context in the n8n UI. | βœ… β˜‘οΈ | | | | | | [require-node-description-fields](docs/rules/require-node-description-fields.md) | Node class description must define all required fields: icon, subtitle | βœ… β˜‘οΈ | | | | | | [require-version](docs/rules/require-version.md) | Require a valid "version" field in community node package.json | βœ… β˜‘οΈ | | | | | | [resource-operation-pattern](docs/rules/resource-operation-pattern.md) | Enforce proper resource/operation pattern for better UX in n8n nodes | βœ… β˜‘οΈ | | | | | | [trigger-node-conventions](docs/rules/trigger-node-conventions.md) | Trigger nodes (class name ends with `Trigger`) must label themselves consistently as triggers | βœ… β˜‘οΈ | | | | | | [valid-author](docs/rules/valid-author.md) | Require a non-empty author name and email in package.json | βœ… β˜‘οΈ | | | | | | [valid-credential-references](docs/rules/valid-credential-references.md) | Ensure credentials referenced in node descriptions exist as credential classes in the package | βœ… β˜‘οΈ | | | πŸ’‘ | | | [valid-description](docs/rules/valid-description.md) | Require a non-empty "description" field in community node package.json | βœ… β˜‘οΈ | | | | | | [valid-node-categories](docs/rules/valid-node-categories.md) | Require supported community node categories in .node.json codex files | βœ… β˜‘οΈ | | | | | | [valid-peer-dependencies](docs/rules/valid-peer-dependencies.md) | Require community node package.json peerDependencies to contain only "n8n-workflow": "*" (and optionally "@n8n/ai-node-sdk") | βœ… β˜‘οΈ | | πŸ”§ | | | | [webhook-lifecycle-complete](docs/rules/webhook-lifecycle-complete.md) | Require webhook trigger nodes to implement the complete webhookMethods lifecycle (checkExists, create, delete) | βœ… β˜‘οΈ | | | | |