Community Packages
Relevant source files
The following files were used as context for generating this wiki page:
- packages/@n8n/node-cli/src/template/templates/shared/default/AGENTS.md
- packages/@n8n/eslint-plugin-community-nodes/README.md
- packages/frontend/editor-ui/src/features/settings/communityNodes/components/nodeCreator/CommunityNodeInfo.vue
- packages/frontend/editor-ui/src/features/settings/communityNodes/components/CommunityPackageManageConfirmModal.vue
- CONTRIBUTING.md
- packages/nodes-base/AGENTS.md
Community packages allow developers to extend n8n functionality by creating and sharing custom nodes and credentials. These packages are distributed via npm and follow a specific naming convention and structure to ensure compatibility with the n8n ecosystem. Users can install, update, and manage these packages directly through the n8n interface.
Sources: packages/@n8n/node-cli/src/template/templates/shared/default/AGENTS.md:7-14, CONTRIBUTING.md:434-436
Package Structure and Configuration
A community package must follow a standardized directory structure and include specific metadata in its package.json file. The n8n field in package.json identifies the package to the n8n platform and specifies the paths to the transpiled JavaScript files for nodes and credentials.
File Organization
Standard community node projects contain two main directories:
nodes/: Contains the source code for one or more nodes.credentials/: Contains the source code for credentials required by the nodes.
Sources: packages/@n8n/node-cli/src/template/templates/shared/default/AGENTS.md:31-38
Metadata Configuration
The package.json file must include an n8n block to define the API version and file locations.
{
"name": "n8n-nodes-example",
"version": "1.0.0",
"n8n": {
"n8nNodesApiVersion": 1,
"strict": true,
"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:42-59
Development Guidelines
Developers use the n8n-node CLI tool for building, linting, and development mode execution. Community packages must adhere to strict naming conventions and technical requirements to ensure stability.
Naming Conventions
Community nodes use a specific naming format: n8n-nodes-<name> or @org/n8n-nodes-<name>. This convention allows n8n to identify and load the packages correctly.
Sources: packages/@n8n/node-cli/src/template/templates/shared/default/AGENTS.md:14, packages/@n8n/eslint-plugin-community-nodes/README.md:104
Linting and Best Practices
The @n8n/eslint-plugin-community-nodes plugin enforces standards through various rules:
- Security: Disallows
eval, process-spawning functions, and hardcoded secrets. - UX: Requires valid icons, documentation URLs, and prevents emoji usage in option names.
- Implementation: Ensures OAuth2 naming consistency and requires proper error wrapping with
NodeApiErrororNodeOperationError.
Sources: packages/@n8n/eslint-plugin-community-nodes/README.md:65-117
Management and Lifecycle
The n8n editor provides a user interface for managing installed community packages. This includes installation, updating, and uninstallation.
Installation and Updates
Users can install packages by providing the npm package name. The system verifies if updates are available by comparing the installed version against the latest version on the npm registry or the n8n vetted list.
Lifecycle Management Flow
The following diagram illustrates the process of managing a community package from the user interface.
The diagram shows the logic for managing package states, including safety checks before uninstallation.
Sources: packages/frontend/editor-ui/src/features/settings/communityNodes/components/CommunityPackageManageConfirmModal.vue:128-193
Package Verification and Statistics
The n8n interface displays metadata about community nodes to help users assess their quality and origin.
| Attribute | Description | Source |
|---|---|---|
| Approved Status | Indicates if a node is vetted or official. | n8n Attribute Service |
| Download Count | Total downloads retrieved from the npm registry. | npm Registry API |
| Publisher | The author or company name associated with the package. | package.json / npm |
| Quick Connect | Availability of streamlined credential setup. | QuickConnect Service |
Workflow Integrity
Before uninstallation or major updates, n8n scans existing workflows to identify any nodes that depend on the package being modified. If nodes are in use, a NodesInWorkflowTable displays the affected workflows to prevent accidental breaks.
Management Actions Summary
| Action | Description | Impact |
|---|---|---|
| Install | Adds package via npm. | Nodes appear in canvas after reload. |
| Update | Pulls newer version from npm. | May introduce breaking changes to nodes. |
| Uninstall | Removes package files. | Workflows using these nodes will fail to load correctly. |
Community packages provide a powerful mechanism for ecosystem growth, allowing for specialized integrations that are not part of the nodes-base package while maintaining strict security and quality standards through automated linting and management tools.