Community Packages & Custom Nodes
Relevant source files
The following files were used as context for generating this wiki page:
Community nodes are a fundamental extensibility mechanism in n8n, allowing developers to create and share custom integrations, triggers, and credentials. These nodes are distributed as npm packages, typically following the naming convention n8n-nodes-<name> or @org/n8n-nodes-<name>. They enable the platform to perform actions, fetch/send data, or manipulate information beyond the built-in node set.
Sources: packages/@n8n/node-cli/src/template/templates/shared/default/AGENTS.md, CONTRIBUTING.md:464-466
Architecture & Project Structure
A community node project is structured as a standard npm package with specific metadata required by the n8n runtime. The primary components are organized into nodes/ and credentials/ directories.
Core Components
- Nodes: Contained within the
nodes/folder, usually in subfolders per node. Each node must have a.node.tsfile implementing theINodeTypeinterface. - Credentials: Contained in the
credentials/folder, defining how n8n connects to external APIs via theICredentialTypeinterface. - Package Manifest: The
package.jsonfile includes a specializedn8nfield that acts as a registry for the package's nodes and credentials.
Sources: packages/@n8n/node-cli/src/template/templates/shared/default/AGENTS.md:27-37, packages/nodes-base/AGENTS.md:6-14
Standard Directory Layout
.
├── nodes/
│ └── Example/
│ ├── Example.node.ts # Node logic
│ └── Example.node.json # Node metadata (optional)
├── credentials/
│ └── Example.credentials.ts # Auth definition
├── package.json # Entry point & n8n metadata
└── tsconfig.json # TypeScript config
Sources: packages/@n8n/node-cli/src/template/templates/shared/default/AGENTS.md:32-37, packages/@n8n/create-node/README.md:197-207
Manifest Registration (package.json)
The n8n object in package.json must point to the transpiled JavaScript files in the dist/ directory.
{
"n8n": {
"n8nNodesApiVersion": 1,
"credentials": [
"dist/credentials/Example.credentials.js"
],
"nodes": [
"dist/nodes/Example/Example.node.js"
]
}
}
Sources: packages/@n8n/node-cli/src/template/templates/shared/default/AGENTS.md:41-54, packages/@n8n/node-cli/README.md:166-176
Development Lifecycle
n8n provides specialized tooling to streamline the creation, testing, and distribution of custom nodes.
Scaffolding and CLI Tools
Developers are encouraged to use @n8n/create-node for initial project scaffolding and @n8n/node-cli for ongoing development tasks.
| Command | Tool | Description |
|---|---|---|
npm create @n8n/node | @n8n/create-node | Interactive project generator with templates. |
n8n-node dev | @n8n/node-cli | Starts n8n with hot reload for the local node package. |
n8n-node build | @n8n/node-cli | Compiles TypeScript and optimizes assets/icons. |
n8n-node lint | @n8n/node-cli | Validates code against n8n community node rules. |
n8n-node release | @n8n/node-cli | Automates versioning, changelog, and npm publishing. |
Sources: packages/@n8n/create-node/README.md:5-20, packages/@n8n/node-cli/README.md:43-91
Local Development Flow
The dev command links the local package to the n8n custom nodes directory (typically ~/.n8n-node-cli/.n8n/custom) and watches for changes.
The diagram shows the hot-reload loop facilitated by the n8n-node dev command.
Sources: packages/@n8n/node-cli/README.md:51-62, packages/@n8n/create-node/README.md:55-65
Implementation Styles
Nodes can be implemented using different architectural styles depending on the complexity of the integration.
Programmatic vs. Declarative
- Programmatic: Uses the
executefunction for custom logic. Best for complex operations, multi-step API calls, or non-REST integrations. - Declarative: Uses
requestDefaultsand routing configurations. n8n automatically generates the UI and handles the API requests based on JSON-like structures.
Sources: packages/nodes-base/AGENTS.md:16-24, packages/@n8n/create-node/README.md:214-219
Trigger Node Types
Trigger nodes initiate workflows and come in three primary forms:
- Webhook Triggers: Implement
webhookand lifecycle methods (checkExists,create,delete). - Polling Triggers: Set
polling: trueand implement thepollmethod. - Generic Triggers: Implement a standard
triggerfunction.
Sources: packages/nodes-base/AGENTS.md:26-32
Quality Standards & Linting
To ensure consistency and security, n8n enforces strict linting rules through the @n8n/eslint-plugin-community-nodes plugin.
Key Linting Rules
- Naming Conventions: Credential class names and filenames must be suffixed with
Api. - Security: Disallows
eval,child_process, and dangerous global variables. - UX: Requires valid
iconproperties and alphabetical ordering for options. - Cloud Readiness: To be eligible for n8n Cloud publication, nodes must pass strict mode checks enabled via
n8n-node cloud-support enable.
Sources: packages/@n8n/eslint-plugin-community-nodes/README.md:37-133, packages/@n8n/node-cli/README.md:112-120
Security Best Practices (Prototype Pollution)
When handling user input, developers must avoid using untrusted values as computed object keys to prevent prototype pollution. The n8n-workflow utility provides safe alternatives.
// UNSAFE
acc[table][key] = value;
// SAFE
import { setSafeObjectProperty, isSafeObjectProperty } from 'n8n-workflow';
if (isSafeObjectProperty(table)) {
setSafeObjectProperty(acc, table, {});
}
Sources: packages/nodes-base/AGENTS.md:61-82
Testing Community Nodes
Testing is divided into two main categories to ensure both unit-level accuracy and workflow-level integration.
- Unit Tests: Use
vitest-mock-extendedandnockto mock external API responses. - Workflow Tests: Utilize the
NodeTestHarnesswith JSON workflow definitions to simulate real-world execution.
Sources: packages/nodes-base/AGENTS.md:46-56
Conclusion
Community packages and custom nodes provide the extensible backbone of n8n. By leveraging the @n8n/node-cli and adhering to established linting and security patterns, developers can create robust integrations that are compatible with both self-hosted and n8n Cloud environments.