Community Packages
Relevant source files
The following files were used as context for generating this wiki page:
Community packages allow users and developers to create, share, and install custom n8n nodes and credentials. These packages extend n8n's native capabilities by integrating with external services and APIs that are not part of the core nodes-base package. All community packages follow a specific naming convention: n8n-nodes-<name> or @org/n8n-nodes-<name>.
Sources: packages/@n8n/node-cli/src/template/templates/shared/default/AGENTS.md:1-12, packages/@n8n/eslint-plugin-community-nodes/README.md:120-120
Package Architecture and Structure
A community package is a standalone npm package containing the logic for one or more n8n nodes and their associated credentials. The standard project structure separates logic into dedicated directories for nodes and credentials.
Directory Layout
nodes/: Contains the TypeScript code for each node, typically organized into subfolders per node.credentials/: Contains credential files that store sensitive information for service authentication.package.json: The manifest file defining dependencies and n8n-specific metadata.
Sources: packages/@n8n/node-cli/src/template/templates/shared/default/AGENTS.md:20-31, packages/@n8n/create-node/README.md:154-165
Configuration Metadata
The package.json file must include an n8n object that identifies the transpiled JavaScript files for the nodes and credentials. This allows n8n to discover and load the extensions from the dist folder.
{
"name": "n8n-nodes-example",
"n8n": {
"n8nNodesApiVersion": 1,
"nodes": [
"dist/nodes/Example/Example.node.js"
],
"credentials": [
"dist/credentials/Example.credentials.js"
]
}
}
Sources: packages/@n8n/node-cli/src/template/templates/shared/default/AGENTS.md:32-51, packages/@n8n/create-node/README.md:167-180
Development Lifecycle
Developers create community nodes using specialized scaffolding and CLI tools that enforce best practices and provide hot-reloading capabilities.
Creation and Scaffolding
The @n8n/create-node tool automates the initial setup. It provides templates for different node styles, such as declarative (JSON-based) or programmatic (full TypeScript control).
| Template | Best For | Features |
|---|---|---|
declarative/custom | REST APIs, simple integrations | JSON-based configuration, automatic UI generation |
programmatic/example | Complex logic, custom operations | Full TypeScript control, advanced error handling |
Sources: packages/@n8n/create-node/README.md:182-192
Technical Workflow
The following diagram illustrates the development-to-publication flow for a community package:
The npm run dev command starts n8n in development mode, enables hot reloading, and links the node to the custom local folder for real-time testing.
Sources: packages/@n8n/create-node/README.md:74-95, packages/@n8n/create-node/README.md:120-136
Quality Control and Linting
To ensure security and compatibility, community packages are subjected to strict linting rules via @n8n/eslint-plugin-community-nodes. These rules are mandatory for packages seeking approval for n8n Cloud.
Key Validation Rules
- Security: Disallows dangerous functions like
evalorchild_process.spawn. It also prevents hardcoded secrets and enforces encryption viathis.helpers.httpRequestWithAuthentication(). - Structure: Validates that node icons exist, package names follow conventions, and all nodes are registered in the
package.jsonn8nobject. - UX: Enforces proper resource/operation patterns and ensures trigger nodes implement the full webhook lifecycle (
checkExists,create,delete).
Sources: packages/@n8n/eslint-plugin-community-nodes/README.md:55-150
Frontend Integration and Display
The n8n Editor UI displays metadata for community nodes, including publisher info, download counts, and verification status.
Verification and Trust
The UI identifies nodes as "Official", "Approved", or "Unverified" based on attributes fetched from the node types store.
| Status | Icon | Description |
|---|---|---|
| Approved | shield-half | Node meets verification standards |
| Unverified | box | Node has not been reviewed by n8n |
| Official | shield-half | Officially supported node |
Discovery Logic
The editor UI fetches package metadata from both internal n8n stores and the npm registry. It tracks total downloads and maintainer information to provide users with a "Trust Score" context.
Summary
Community Packages provide a structured extension mechanism for n8n. By utilizing the n8n-node CLI and following mandated ESLint rules, developers can build integrations that are secure, high-quality, and eligible for distribution on n8n Cloud. These packages are managed through npm and integrated into the editor UI with clear trust indicators for end users.