n8n-impl-custom-nodes

n8n Custom Node Development

Build, test, and publish custom n8n community nodes using TypeScript.

Quick Reference

Task	Command / Action
Scaffold project	Clone n8n-io/n8n-nodes-starter from GitHub
Install dependencies	npm install
Development mode	npm run dev (hot-reload at http://localhost:5678)
Build	npm run build (compiles to dist/)
Lint	npm run lint
Publish	npm publish (package name MUST start with n8n-nodes-)

Decision Tree: Programmatic vs Declarative

Need a custom node?
├── Is it a REST API wrapper with standard CRUD operations?
│   └── YES → Use DECLARATIVE style (routing in properties, NO execute() method)
├── Does it require complex data transformation or custom logic?
│   └── YES → Use PROGRAMMATIC style (execute() method with full control)
└── Does it need to call multiple APIs or combine data sources?
    └── YES → Use PROGRAMMATIC style

Project Structure

n8n-nodes-<service-name>/
├── package.json              # Node registration via n8n field (CRITICAL)
├── tsconfig.json             # TypeScript config
├── credentials/
│   └── MyApi.credentials.ts  # Credential definitions
├── nodes/
│   └── MyNode/
│       ├── MyNode.node.ts    # Main node implementation
│       ├── MyNode.node.json  # Codex metadata (optional, for search/AI)
│       └── resources/        # Resource descriptions (declarative style)
├── icons/
│   └── my-icon.svg           # Node icon (SVG or PNG, max 60x60px)
└── dist/                     # Compiled output (generated by build)

package.json n8n Field (CRITICAL)

The n8n field in package.json registers your nodes and credentials with n8n.

{
    "name": "n8n-nodes-myservice",
    "version": "0.1.0",
    "keywords": ["n8n-community-node-package"],
    "n8n": {
        "n8nNodesApiVersion": 1,
        "credentials": [
            "dist/credentials/MyApi.credentials.js"
        ],
        "nodes": [
            "dist/nodes/MyNode/MyNode.node.js"
        ]
    },
    "files": ["dist"],
    "peerDependencies": {
        "n8n-workflow": "*"
    }
}