Hai sviluppato un’integrazione utile per il tuo team e vuoi condividerla con il mondo? Questa guida end‑to‑end ti mostra come pubblicare un nodo community n8n nel modo giusto: dallo scaffold con il CLI ufficiale alla definizione della chiave n8n in package.json, dagli standard UX alla gestione sicura delle credenziali (API key e OAuth2), fino a linting, build, CI/CD, pubblicazione su npm e submission per la verifica. Scoprirai come rispettare le n8n community nodes guidelines, le convenzioni naming pacchetti n8n-nodes, come strutturare README ed esempi per nodi n8n e come ottenere discoverability nel pannello Community Nodes. Chiudiamo con consigli per marketing e adozione, più un troubleshooting pragmatico. L’obiettivo è ridurre attrito, velocizzare il rilascio e aumentare l’impatto del tuo lavoro.
[IMG: panoramica flusso: scaffold → sviluppo e test → build/lint → npm publish → verifica → discoverability]
Setup e requisiti: cosa serve per partire
Prima di iniziare, assicurati di avere:
- Requisiti di base: Node.js LTS, account npm (consigliata 2FA), repo Git pubblico, conoscenza TypeScript.
- n8n node development CLI: l’utility ufficiale n8n-node per creare lo scaffold, lanciare il dev server e rispettare le n8n community nodes guidelines.
- Ambiente di test n8n: un’istanza locale o cloud per provare il nodo, installarlo e verificare UX e logica.
Perché il CLI ufficiale:
- Ti guida sul naming corretto (convenzioni naming pacchetti n8n-nodes) e sulla struttura compatibile con la verifica.
- Puoi scegliere template “declarative” (HTTP API) o “custom” (programmatico) in base alle esigenze di integrazione.
Comandi iniziali tipici:
# Crea il progetto (scaffold)
npx n8n-node new n8n-nodes-myintegration
# Variante con template
npx n8n-node new --template declarative n8n-nodes-myintegration
# Lancia ambiente di sviluppo
npm run dev
# Lint e build
npm run lint
npm run build
[IMG: terminale con esecuzione di npx n8n-node new e struttura cartelle generata]
Naming, package.json e chiave “n8n”: le basi per l’approvazione
La discoverability parte dal package.json. Regole essenziali:
- Convenzioni di naming del pacchetto: prefisso n8n-nodes- o @scope/n8n-nodes- (es. n8n-nodes-weather o @acme/n8n-nodes-weather).
- Keyword per l’indicizzazione: includi “n8n-community-node-package”.
- Chiave n8n in package.json: dichiara nodes e credentials per permettere a n8n di individuare i file.
Esempio package.json minimo:
{
"name": "n8n-nodes-myintegration",
"version": "1.0.0",
"description": "Community node for MyIntegration",
"keywords": [
"n8n-community-node-package",
"n8n",
"integration",
"automation"
],
"repository": "https://github.com/your-org/n8n-nodes-myintegration",
"author": "Your Name <you@example.com>",
"license": "MIT",
"engines": { "node": ">=18" },
"main": "dist/index.js",
"n8n": {
"nodes": [
"dist/nodes/MyIntegration/MyIntegration.node.js"
],
"credentials": [
"dist/credentials/MyIntegrationApi.credentials.js"
]
},
"scripts": {
"build": "tsc -p tsconfig.json",
"lint": "eslint . --ext .ts",
"dev": "n8n-node dev"
},
"devDependencies": {
"typescript": "^5.0.0",
"eslint": "^8.0.0",
"prettier": "^3.0.0"
}
}
Note importanti:
- Inserisci “nodes” e “credentials” nella chiave n8n con i path buildati (dist/…).
- Mantieni semver e release management per n8n puliti (0.x per early, poi stable). Tagga le release.
[IMG: editor con package.json evidenziando sezione “n8n” e keywords]
Implementazione: struttura TypeScript del nodo e credenziali
Implementazione di nodes e credentials in TypeScript è lo standard per performance e manutenibilità.
Nodo (scheletro):
import type { IExecuteFunctions, INodeExecutionData, INodeType, INodeTypeDescription } from 'n8n-workflow';
export class MyIntegration implements INodeType {
description: INodeTypeDescription = {
displayName: 'MyIntegration',
name: 'myIntegration',
group: ['transform'],
version: 1,
description: 'Interact with MyIntegration API',
defaults: { name: 'MyIntegration' },
inputs: ['main'],
outputs: ['main'],
credentials: [{ name: 'myIntegrationApi', required: true }],
properties: [
{
displayName: 'Resource',
name: 'resource',
type: 'options',
options: [
{ name: 'Contact', value: 'contact' },
{ name: 'Order', value: 'order' }
],
default: 'contact'
},
{
displayName: 'Operation',
name: 'operation',
type: 'options',
options: [
{ name: 'Create', value: 'create' },
{ name: 'Get', value: 'get' }
],
default: 'get'
},
// ...altri parametri (campi, query, body, ecc.)
],
};
async execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]> {
const items = this.getInputData();
// Esegui chiamate API e ritorna i risultati per item
return [items];
}
}
Credenziali (API key/OAuth2):
import type { ICredentialType, INodeProperties } from 'n8n-workflow';
export class MyIntegrationApi implements ICredentialType {
name = 'myIntegrationApi';
displayName = 'MyIntegration API';
documentationUrl = 'https://docs.myintegration.com';
properties: INodeProperties[] = [
{
displayName: 'API Key',
name: 'apiKey',
type: 'string',
typeOptions: { password: true },
default: ''
}
];
}
Linee guida UX:
- standard UX per nodi n8n: displayName chiari, descrizioni sintetiche, placeholder utili, validazioni sui parametri.
- credenziali OAuth2 in n8n: se l’API lo supporta, fornisci anche un credential OAuth2 (scopes minimi necessari).
[IMG: IDE con MyIntegration.node.ts e MyIntegrationApi.credentials.ts]
UX guidelines: operazioni, parametri e coerenza con l’ecosistema
Per candidarsi a verifica:
- Operazioni CRUD: includi le operazioni comuni per ogni risorsa quando ha senso, in linea con le UX guidelines for community nodes.
- Naming e vocabolario: usa termini consistenti con altri nodi (es. “Create”, “Get”, “Update”, “Delete”; “Resource”/“Operation”).
- Credenziali: i campi sensibili devono essere password; includi OAuth quando disponibile.
- Node structure: differenzia chiaramente risorsa e operazioni; usa opzioni e collection per parametri avanzati; fornisci descrizioni e placeholder che suggeriscano il formato.
- Output: evita output “sorpresa”; documenta lo shape della risposta nel README ed esempi.
Insight: l’UX coerente riduce le frizioni in adozione e velocizza la revisione/approvazione.
[IMG: canvas n8n con pannello del nodo che mostra Resource/Operation e campi ben etichettati]
Test locale, esempi e mock: ridurre i roundtrip
Prima della pubblicazione:
- Test locale nell’istanza n8n: installa il pacchetto buildato e prova i workflow di esempio.
- Esempi di workflow: includi 2–3 JSON pronti all’uso nel repo (importabili dall’utente).
- Mock di API: per test ripetibili, prepara risposte di esempio (file JSON) o strumenti di mock per endpoint comuni.
- Linting TypeScript per n8n nodes: esegui npm run lint e correggi warning/errori.
- Build: npm run build deve produrre dist/ completo (nodes + credentials).
Esempio script install locale (da cartella del nodo):
npm run build
# In un ambiente n8n locale, installa il pacchetto (community nodes attivati)
# oppure usa la UI Community Nodes inserendo il nome del package pubblicato.
[IMG: istanza n8n locale con workflow di test e nodo custom installato]
CI/CD: automazione di lint, build e release management
Automatizzare evita regressioni:
- GitHub Actions: pipeline con job per lint, build, test (eventuali) e pubblicazione condizionata su tag.
- semver e release management per n8n: usa tag vX.Y.Z; genera changelog e badge nel README.
Esempio workflow base (estratto):
name: CI
on:
push:
branches: [ main ]
pull_request:
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '18'
registry-url: 'https://registry.npmjs.org'
- run: npm ci
- run: npm run lint
- run: npm run build
Per il publish:
- Richiedi approvazione manuale o pubblica su creazione tag semantico.
- Pubblicazione pacchetto npm per n8n con 2FA consigliata.
[IMG: screenshot pipeline GitHub Actions con passi lint/build e badge verde]
Pubblicazione su npm e verifica: come farsi trovare
Passi consigliati:
- npm publish: assicurati che dist/ contenga i file indicati nella chiave n8n (nodes/credentials).
- Conformità: naming corretto,
Scopri la consulenza →