Nodes & Integrations

Relevant source files

The following files were used as context for generating this wiki page:

• packages/nodes-base/AGENTS.md
• packages/@n8n/node-cli/src/template/templates/shared/default/AGENTS.md
• packages/@n8n/create-node/README.md
• packages/@n8n/eslint-plugin-community-nodes/README.md
• CONTRIBUTING.md
• AGENTS.md

Nodes are the fundamental building blocks of n8n workflows. They are discrete units of logic that perform specific actions, such as fetching data from an external API, transforming JSON structures, or triggering a workflow based on an external event. Integrations are implemented through these nodes, often requiring credentials to securely connect to third-party services.

The system supports various node types, including triggers (webhooks, polling, and generic), programmatic nodes for custom logic, and declarative nodes that use configuration-driven routing. Community nodes allow developers to extend the platform by creating and sharing custom integrations.

Sources: packages/@n8n/node-cli/src/template/templates/shared/default/AGENTS.md:3-9, packages/nodes-base/AGENTS.md:12-23

Node Architecture and Implementation

Every node in n8n must implement the INodeType interface. This interface defines the node's metadata, its user interface configuration via INodeTypeDescription, and the core logic execution methods.

Core Interface Components

Method/Property	Description
description	Contains INodeTypeDescription for metadata and UI configuration.
execute()	Main logic for programmatic nodes.
poll()	Logic for polling-based triggers.
trigger()	Logic for generic triggers.
webhook()	Logic for receiving and processing webhook requests.
methods	Helper methods like loadOptions, listSearch, and credentialTest.

Sources: packages/nodes-base/AGENTS.md:5-10

Execution Flow

The following diagram illustrates the high-level execution flow when a node is processed within a workflow.

The workflow engine identifies the node type and routes execution to the appropriate internal method defined in the node's class.
Sources: packages/nodes-base/AGENTS.md:12-23, AGENTS.md:104-106

Node Types and Styles

n8n distinguishes between several development styles and functional types of nodes.

Programmatic vs. Declarative

• Programmatic Nodes: These nodes use the execute function to define custom TypeScript logic. This is preferred for complex integrations that require multi-step data processing or unique API handling.
• Declarative Nodes: These rely on requestDefaults and routing configurations in the node description rather than a manual execute function. This style is often used for standard REST API integrations.

Sources: packages/nodes-base/AGENTS.md:12-16, packages/@n8n/create-node/README.md:209-213

Trigger Nodes

Trigger nodes are responsible for initiating workflow execution. They fall into three main categories:

1. Webhook Triggers: Implement the webhook method and lifecycle methods like checkExists, create, and delete.
2. Polling Triggers: Use the poll method with polling: true set in the description. They often use getWorkflowStaticData to persist state between runs.
3. Generic Triggers: Implement a standard trigger function for custom event sources.

Sources: packages/nodes-base/AGENTS.md:18-23

Credentials System

Credentials are separate entities that store sensitive connection information. They are defined in the credentials/ directory and implement the ICredentialType interface.

Nodes reference credentials by their internal name. The authenticate property defines how the credentials are used (e.g., Header Auth, OAuth2), while test allows users to verify connectivity within the UI.
Sources: packages/nodes-base/AGENTS.md:43-52, packages/@n8n/node-cli/src/template/templates/shared/default/AGENTS.md:30-32

Community Nodes and Scaffolding

The @n8n/create-node CLI tool is used to scaffold new community node packages. These packages follow a specific structure to be recognized by n8n.

Project Structure

A standard community node package consists of:

• nodes/: A directory containing the node implementation files (.node.ts and .node.json).
• credentials/: A directory for credential definitions (.credentials.ts).
• package.json: Contains a special n8n field mapping the transpiled JS files.

{
  "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:33-66, packages/@n8n/create-node/README.md:180-192

Best Practices and Security

Secure Property Access

When handling dynamic object keys from user input (e.g., this.getNodeParameter), developers must use safety helpers to prevent prototype pollution.

import { setSafeObjectProperty, isSafeObjectProperty } from 'n8n-workflow';

if (isSafeObjectProperty(table) && acc[table] === undefined) {
	setSafeObjectProperty(acc, table, {});
}

Sources: packages/nodes-base/AGENTS.md:82-95

Development and Linting Rules

The @n8n/eslint-plugin-community-nodes enforces several constraints:

• Naming: Credentials must end with Api (e.g., myServiceApi).
• Icons: Nodes and credentials must have icons defined.
• Parameters: Every parameter must declare a default value.
• Errors: NodeApiError or NodeOperationError must be used for user-facing errors to preserve context.

Sources: packages/@n8n/eslint-plugin-community-nodes/README.md:44-120

Conclusion

The node system provides a flexible framework for extending n8n. By abstracting the complexities of API communication into declarative or programmatic structures and isolating sensitive data within the credentials system, n8n ensures that integrations are both powerful and secure. Developers are encouraged to use scaffolding tools and adhere to linting guidelines to maintain compatibility and eligibility for the n8n Cloud version.