Developing Built-in Nodes

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
• CONTRIBUTING.md
• packages/@n8n/create-node/README.md
• packages/@n8n/node-cli/README.md
• packages/@n8n/workflow-sdk/src/generate-types/generate-types.ts

Built-in nodes provide the primary functionality within n8n workflows. They execute actions, trigger events, and manipulate data. Every node implements the INodeType interface, which defines its metadata and execution logic. Developers build nodes using either a programmatic approach for custom logic or a declarative approach for standard API integrations.

Sources: packages/nodes-base/AGENTS.md:7-10, packages/@n8n/node-cli/src/template/templates/shared/default/AGENTS.md:4-9

Node Architecture

Nodes consist of two main parts: the UI configuration and the execution logic. The description field in the node class contains the metadata required by the n8n editor, including its name, icon, and parameters. The execution logic resides in methods like execute, trigger, or webhook, depending on the node's purpose.

Core Interface

The INodeType interface governs all node implementations.

This diagram shows the relationship between the node implementation and its descriptive metadata.
Sources: packages/nodes-base/AGENTS.md:9-16, packages/@n8n/workflow-sdk/src/generate-types/generate-types.ts:182-192

Node Implementation Styles

Style	Use Case	Implementation Details
Programmatic	Custom logic and complex transformations	Uses the execute() function for manual item processing.
Declarative	Standard REST API integrations	Uses requestDefaults and routing configurations instead of manual code.
Trigger	Starting workflows based on external events	Implements trigger(), webhook(), or poll().

Sources: packages/nodes-base/AGENTS.md:20-40

Project Structure

A node project organizes code into nodes/ and credentials/ directories. The package.json file contains an n8n object that maps the transpiled JavaScript paths for the core components.

{
  "name": "n8n-nodes-example",
  "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:30-49

Development Workflow

Developers use the @n8n/create-node scaffolding tool to start new projects. This tool generates a project with pre-configured build and linting scripts.

CLI Commands

Command	Action
npm create @n8n/node	Starts the interactive node creation wizard.
n8n-node dev	Runs n8n in development mode and watches for file changes.
n8n-node build	Compiles TypeScript into JavaScript and bundles assets.
n8n-node lint	Validates code against n8n's strict security and style guidelines.

Sources: packages/@n8n/create-node/README.md:12-25, packages/@n8n/node-cli/README.md:21-42

Hot Reloading

You can enable hot reloading by setting the N8N_DEV_RELOAD environment variable to true. This activates a file watcher that automatically refreshes the node definitions on disk without a full server restart.
Sources: CONTRIBUTING.md:289-305

Parameter Configuration

Node parameters define the user interface in the editor. Common types include string, number, boolean, and options.

Dynamic Features

• Load Options: Use loadOptionsMethod in typeOptions to fetch dropdown values from an API at runtime.
• Resource Locator: Use resourceLocator to allow users to select items by list, ID, or URL. It requires a searchListMethod.
• Display Options: Use displayOptions to show or hide parameters based on the values of other fields.

This flowchart shows how n8n resolves parameter values for the user interface.
Sources: packages/nodes-base/AGENTS.md:42-53, packages/@n8n/workflow-sdk/src/generate-types/generate-types.ts:602-628

Security and Best Practices

Developers must adhere to strict security patterns when handling dynamic data.

1. Untrusted Object Keys: Never use untrusted values as computed object keys. Use setSafeObjectProperty from n8n-workflow instead.
2. Error Handling: Throw NodeOperationError for user-facing errors and NodeApiError for failures related to external APIs.
3. Type Safety: Avoid using any. Use interfaces for all API responses.
4. Resource Selection: Set noDataExpression: true for resource and operation selectors to prevent users from accidentally using expressions where literals are required.

Sources: packages/nodes-base/AGENTS.md:94-110, packages/nodes-base/AGENTS.md:118-124, packages/@n8n/workflow-sdk/src/generate-types/generate-types.ts:66-70

Testing Nodes

Nodes require both unit and workflow tests to ensure reliability.

• Unit Tests: Use vitest-mock-extended to mock the node interfaces and nock to intercept HTTP requests.
• Workflow Tests: Use the NodeTestHarness with JSON workflow definitions to simulate full execution paths.

Sources: packages/nodes-base/AGENTS.md:78-90

Summary

Developing built-in nodes involves defining metadata through INodeTypeDescription and implementing execution logic in the INodeType class. Developers use the n8n-node CLI for scaffolding and development. Adherence to security guidelines, such as using safe object property helpers and proper error classes, ensures the stability and safety of the automation platform.