mirror of
https://github.com/n8n-io/n8n.git
synced 2024-12-30 06:59:41 -08:00
2a8f1753e8
Some checks are pending
Test Master / install-and-build (push) Waiting to run
Test Master / Unit tests (18.x) (push) Blocked by required conditions
Test Master / Unit tests (20.x) (push) Blocked by required conditions
Test Master / Unit tests (22.4) (push) Blocked by required conditions
Test Master / Lint (push) Blocked by required conditions
Test Master / Notify Slack on failure (push) Blocked by required conditions
219 lines
8.5 KiB
Markdown
219 lines
8.5 KiB
Markdown
|
|
|
|
# n8n-node-dev
|
|
|
|
Currently very simple and not very sophisticated CLI which makes it easier
|
|
to create credentials and nodes in TypeScript for n8n.
|
|
|
|
```
|
|
npm install n8n-node-dev -g
|
|
```
|
|
|
|
## Contents
|
|
|
|
- [Usage](#usage)
|
|
- [Commands](#commands)
|
|
- [Create a node](#create-a-node)
|
|
- [Node Type](#node-type)
|
|
- [Node Type Description](#node-type-description)
|
|
- [Node Properties](#node-properties)
|
|
- [Node Property Options](#node-property-options)
|
|
- [License](#license)
|
|
|
|
## Usage
|
|
|
|
The commandline tool can be started with `n8n-node-dev <COMMAND>`
|
|
|
|
## Commands
|
|
|
|
The following commands exist:
|
|
|
|
### build
|
|
|
|
Builds credentials and nodes in the current folder and copies them into the
|
|
n8n custom extension folder (`~/.n8n/custom/`) unless destination path is
|
|
overwritten with `--destination <FOLDER_PATH>`
|
|
|
|
When "--watch" gets set it starts in watch mode and automatically builds and
|
|
copies files whenever they change. To stop press "ctrl + c".
|
|
|
|
### new
|
|
|
|
Creates new basic credentials or node of the selected type to have a first starting point.
|
|
|
|
## Create a node
|
|
|
|
The easiest way to create a new node is via the "n8n-node-dev" cli. It sets up
|
|
all the basics.
|
|
|
|
A n8n node is a JavaScript file (normally written in TypeScript) which describes
|
|
some basic information (like name, description, ...) and also at least one method.
|
|
Depending on which method gets implemented defines if it is a regular-, trigger-
|
|
or webhook-node.
|
|
|
|
A simple regular node which:
|
|
|
|
- defines one node property
|
|
- sets its value to all items it receives
|
|
|
|
would look like this:
|
|
|
|
File named: `MyNode.node.ts`
|
|
|
|
```TypeScript
|
|
import {
|
|
IExecuteFunctions,
|
|
INodeExecutionData,
|
|
INodeType,
|
|
INodeTypeDescription,
|
|
} from 'n8n-workflow';
|
|
|
|
|
|
export class MyNode implements INodeType {
|
|
description: INodeTypeDescription = {
|
|
displayName: 'My Node',
|
|
name: 'myNode',
|
|
group: ['transform'],
|
|
version: 1,
|
|
description: 'Adds "myString" on all items to defined value.',
|
|
defaults: {
|
|
name: 'My Node',
|
|
color: '#772244',
|
|
},
|
|
inputs: ['main'],
|
|
outputs: ['main'],
|
|
properties: [
|
|
// Node properties which the user gets displayed and
|
|
// can change on the node.
|
|
{
|
|
displayName: 'My String',
|
|
name: 'myString',
|
|
type: 'string',
|
|
default: '',
|
|
placeholder: 'Placeholder value',
|
|
description: 'The description text',
|
|
}
|
|
]
|
|
};
|
|
|
|
|
|
async execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]> {
|
|
|
|
const items = this.getInputData();
|
|
|
|
let item: INodeExecutionData;
|
|
let myString: string;
|
|
|
|
// Itterates over all input items and add the key "myString" with the
|
|
// value the parameter "myString" resolves to.
|
|
// (This could be a different value for each item in case it contains an expression)
|
|
for (let itemIndex = 0; itemIndex < items.length; itemIndex++) {
|
|
myString = this.getNodeParameter('myString', itemIndex, '') as string;
|
|
item = items[itemIndex];
|
|
|
|
item.json['myString'] = myString;
|
|
}
|
|
|
|
return [items];
|
|
|
|
}
|
|
}
|
|
```
|
|
|
|
The "description" property has to be set on all nodes because it contains all
|
|
the base information. Additionally all nodes have to have exactly one of the
|
|
following methods defined which contains the actual logic:
|
|
|
|
**Regular node**
|
|
|
|
Method is called when the workflow gets executed
|
|
|
|
- `execute`: Executed once no matter how many items
|
|
|
|
By default, `execute` should always be used, especially when creating a
|
|
third-party integration. The reason for this is that it provides much more
|
|
flexibility and allows, for example, returning a different number of items than
|
|
it received as input. This becomes crucial when a node needs to query data such as _return
|
|
all users_. In such cases, the node typically receives only one input item but returns as
|
|
many items as there are users. Therefore, when in doubt, it is recommended to use `execute`!
|
|
|
|
**Trigger node**
|
|
|
|
Method is called once when the workflow gets activated. It can then trigger workflow runs and provide the necessary data by itself.
|
|
|
|
- `trigger`
|
|
|
|
**Webhook node**
|
|
|
|
Method is called when webhook gets called.
|
|
|
|
- `webhook`
|
|
|
|
### Node Type
|
|
|
|
Property overview
|
|
|
|
- **description** [required]: Describes the node like its name, properties, hooks, ... see `Node Type Description` bellow.
|
|
- **execute** [optional]: Method is called when the workflow gets executed (once).
|
|
- **hooks** [optional]: The hook methods.
|
|
- **methods** [optional]: Additional methods. Currently only "loadOptions" exists which allows loading options for parameters from external services
|
|
- **trigger** [optional]: Method is called once when the workflow gets activated.
|
|
- **webhook** [optional]: Method is called when webhook gets called.
|
|
- **webhookMethods** [optional]: Methods to setup webhooks on external services.
|
|
|
|
### Node Type Description
|
|
|
|
The following properties can be set in the node description:
|
|
|
|
- **credentials** [optional]: Credentials the node requests access to
|
|
- **defaults** [required]: Default "name" and "color" to set on node when it gets created
|
|
- **displayName** [required]: Name to display users in Editor UI
|
|
- **description** [required]: Description to display users in Editor UI
|
|
- **group** [required]: Node group for example "transform" or "trigger"
|
|
- **hooks** [optional]: Methods to execute at different points in time like when the workflow gets activated or deactivated
|
|
- **icon** [optional]: Icon to display (can be an icon or a font awesome icon)
|
|
- **inputs** [required]: Types of inputs the node has (currently only "main" exists) and the amount
|
|
- **outputs** [required]: Types of outputs the node has (currently only "main" exists) and the amount
|
|
- **outputNames** [optional]: In case a node has multiple outputs, names can be set that users know what data to expect
|
|
- **maxNodes** [optional]: If an unlimited number of nodes of that type cannot exist in a workflow, the max-amount can be specified
|
|
- **name** [required]: Name of the node (for n8n to use internally, in camelCase)
|
|
- **properties** [required]: Properties which get displayed in the Editor UI and can be set by the user
|
|
- **subtitle** [optional]: Text which should be displayed underneath the name of the node in the Editor UI (can be an expression)
|
|
- **version** [required]: Version of the node. Currently always "1" (integer). For future usage, does not get used yet
|
|
- **webhooks** [optional]: Webhooks the node should listen to
|
|
|
|
### Node Properties
|
|
|
|
The following properties can be set in the node properties:
|
|
|
|
- **default** [required]: Default value of the property
|
|
- **description** [required]: Description that is displayed to users in the Editor UI
|
|
- **displayName** [required]: Name that is displayed to users in the Editor UI
|
|
- **displayOptions** [optional]: Defines logic to decide if a property should be displayed or not
|
|
- **name** [required]: Name of the property (for n8n to use internally, in camelCase)
|
|
- **options** [optional]: The options the user can select when type of property is "collection", "fixedCollection" or "options"
|
|
- **placeholder** [optional]: Placeholder text that is displayed to users in the Editor UI
|
|
- **type** [required]: Type of the property. If it is for example a "string", "number", ...
|
|
- **typeOptions** [optional]: Additional options for type. Like for example the min or max value of a number
|
|
- **required** [optional]: Defines if the value has to be set or if it can stay empty
|
|
|
|
### Node Property Options
|
|
|
|
The following properties can be set in the node property options:
|
|
|
|
All properties are optional. However, most only work when the node-property is of a specfic type.
|
|
|
|
- **alwaysOpenEditWindow** [type: json]: If set then the "Editor Window" will always open when the user tries to edit the field. Helpful if long text is typically used in the property
|
|
- **loadOptionsMethod** [type: options]: Method to use to load options from an external service
|
|
- **maxValue** [type: number]: Maximum value of the number
|
|
- **minValue** [type: number]: Minimum value of the number
|
|
- **multipleValues** [type: all]: If set the property gets turned into an Array and the user can add multiple values
|
|
- **multipleValueButtonText** [type: all]: Custom text for add button in case "multipleValues" were set
|
|
- **numberPrecision** [type: number]: The precision of the number. By default, it is "0" and will only allow integers
|
|
- **password** [type: string]: If a password field should be displayed (normally only used by credentials because all node data is not encrypted and gets saved in clear-text)
|
|
- **rows** [type: string]: Number of rows the input field should have. By default it is "1"
|
|
|
|
## License
|
|
|
|
You can find the license information [here](https://github.com/n8n-io/n8n/blob/master/README.md#license)
|