File size: 8,732 Bytes
aec3094 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 | 
# 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)
|