Come Costruire e Pubblicare un Community Node sul Marketplace di n8n

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.

📚 Nuovo a n8n? Parti dalla guida completa: cos’è n8n e come funziona.

[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,