Community Node Packages
Relevant source files
The following files were used as context for generating this wiki page:
Community Node Packages allow developers to extend n8n's functionality by creating custom nodes and making them available to the wider community via npm. This system provides a standardized development environment, tooling, and quality checks to ensure consistency and reliability. The primary tools for this process are @n8n/create-node for scaffolding and @n8n/node-cli for managing the development lifecycle.
While n8n's core repository contains built-in nodes in /packages/nodes-base, community nodes are developed in separate repositories and published independently. This allows the ecosystem to grow without requiring direct changes to the main n8n codebase.
Sources: CONTRIBUTING.md:213-214, packages/@n8n/create-node/README.md:3-5, packages/@n8n/node-cli/README.md:3-5
Creating a New Node
The recommended way to start a new community node project is by using the @n8n/create-node scaffolding tool. This interactive CLI generates a new project with best practices and all necessary boilerplate code.
Sources: packages/@n8n/create-node/README.md:7-9, packages/@n8n/node-cli/README.md:7-9
Quick Start
To create a new node, run the following command and follow the interactive prompts:
npm create @n8n/node@latest
The CLI guides you through the initial setup, asking for the node name, type (e.g., HTTP API), API base URL, and authentication method.
Sources: packages/@n8n/create-node/README.md:7-9, 28-51
This diagram illustrates the interactive setup flow.
Command Line Options
You can also provide options directly to the new command, which is used internally by npm create @n8n/node.
| Flag | Description | Available Templates |
|---|---|---|
-f, --force | Overwrite destination folder if it already exists. | declarative/custom |
--skip-install | Skip automatic dependency installation. | declarative/github-issues |
--template <template> | Specify which template to use. | programmatic/example |
Sources: packages/@n8n/node-cli/README.md:27-33
Development Workflow
The generated project includes several npm scripts that wrap @n8n/node-cli commands to streamline the development process.
Sources: packages/@n8n/create-node/README.md:68-87
This diagram shows the typical development cycle for a community node.
Key Commands
| Command | Description | Underlying CLI Command |
|---|---|---|
npm run dev | Starts n8n in development mode with hot reload for your node. It links your node to ~/.n8n-node-cli/.n8n/custom and rebuilds on file changes. | n8n-node dev |
npm run build | Compiles your TypeScript code and prepares the node for distribution in the dist/ folder. | n8n-node build |
npm run lint | Lints the node code to check for style and convention issues. | n8n-node lint |
npm run lint:fix | Automatically fixes linting problems. | n8n-node lint --fix |
npm run release | Handles the entire release process, including building, linting, versioning, and publishing to npm. | n8n-node release |
Sources: packages/@n8n/create-node/README.md:68-87, packages/@n8n/node-cli/README.md:11-23, 50-66, 88-94, 111-113
Project Structure and Configuration
The CLI tools expect a specific project structure for building and development.
Directory Layout
A typical community node project has the following structure:
my-awesome-api-node/
├── src/
│ ├── nodes/
│ │ └── MyAwesomeApi/
│ │ ├── MyAwesomeApi.node.ts # Main node logic
│ │ └── MyAwesomeApi.node.json # Node metadata
│ └── credentials/
│ └── MyAwesomeApiAuth.credentials.ts
├── package.json
├── tsconfig.json
└── README.md
Sources: packages/@n8n/create-node/README.md:122-133, packages/@n8n/node-cli/README.md:146-155
This diagram shows the expected folder structure.
package.json Configuration
The CLI reads configuration from a special n8n object within your package.json. This object specifies the API version and paths to the compiled node and credential files.
{
"name": "n8n-nodes-my-awesome-node",
"n8n": {
"n8nNodesApiVersion": 1,
"nodes": [
"dist/nodes/MyAwesomeApi/MyAwesomeApi.node.js"
],
"credentials": [
"dist/credentials/MyAwesomeApiAuth.credentials.js"
]
}
}
Sources: packages/@n8n/create-node/README.md:136-149, packages/@n8n/node-cli/README.md:158-171
Code Quality and Linting
To ensure consistency and adherence to best practices, n8n provides an ESLint plugin specifically for community nodes: @n8n/eslint-plugin-community-nodes.
Sources: packages/@n8n/eslint-plugin-community-nodes/README.md:3-5
ESLint Configuration
To use the recommended rules, add the plugin to your eslint.config.js:
import { n8nCommunityNodesPlugin } from '@n8n/eslint-plugin-community-nodes';
export default [
// …
n8nCommunityNodesPlugin.configs.recommended,
{
rules: {
'@n8n/community-nodes/node-usable-as-tool': 'warn',
},
},
];
Sources: packages/@n8n/eslint-plugin-community-nodes/README.md:15-26
Linting Rules
The plugin enforces several rules critical for node quality and security.
| Rule | Description |
|---|---|
credential-documentation-url | Enforces a valid documentationUrl for credentials. |
credential-password-field | Ensures sensitive credential fields are marked as passwords. |
credential-test-required | Requires credentials to have a test method. |
icon-validation | Validates that node and credential icons exist and are in the correct format. |
no-credential-reuse | Prevents security issues from reusing credentials across packages. |
no-deprecated-workflow-functions | Disallows usage of deprecated functions from n8n-workflow. |
no-restricted-globals | Disallows usage of restricted global variables. |
no-restricted-imports | Disallows usage of restricted imports. |
node-usable-as-tool | Ensures node classes have the usableAsTool property. |
package-name-convention | Enforces the correct n8n-nodes-* package naming convention. |
resource-operation-pattern | Enforces the proper resource/operation pattern for better UX. |
Sources: packages/@n8n/eslint-plugin-community-nodes/README.md:35-58
n8n Cloud Support
The n8n-node cloud-support command manages eligibility for n8n Cloud. In strict mode, the node must use the default ESLint config and pass all community rules.
Sources: packages/@n8n/node-cli/README.md:96-109
Publishing
The npm run release command automates the entire publishing process using release-it.
This sequence diagram shows the steps performed by the release command.
Legacy Tools
Before the introduction of @n8n/node-cli, the n8n-node-dev tool was used. It provides similar build and new commands but is considered the older way of developing nodes. The build command compiles nodes and copies them to ~/.n8n/custom/, and can be run in watch mode.
Sources: packages/node-dev/README.md:15-25