AGENTS.md

1# AGENTS.md
2 
3Guidance for node development in the nodes-base package.
4 
5## Node Structure
6 
7Every node implements the `INodeType` interface with:
8- `description: INodeTypeDescription` - Node metadata and UI configuration
9- `execute?()` - For programmatic nodes
10- `poll?()` - For polling triggers (set `polling: true` in description)
11- `trigger?()` - For generic triggers
12- `webhook?()` - For webhook triggers
13- `webhookMethods?` - Webhook lifecycle (checkExists, create, delete)
14- `methods?` - loadOptions, listSearch, credentialTest, resourceMapping
15 
16## Node Types
17 
18### Programmatic Nodes
19Use `execute` function for custom logic. Example: `nodes/Discord/v2/DiscordV2.node.ts`
20 
21### Declarative Nodes
22Use `requestDefaults` and routing configuration instead of `execute`. Example: `nodes/Okta/Okta.node.ts`
23 
24### Trigger Nodes
25- **Webhook triggers**: Implement `webhook` and `webhookMethods` (checkExists, create, delete). Example: `nodes/Microsoft/Teams/MicrosoftTeamsTrigger.node.ts`
26- **Polling triggers**: Set `polling: true` and implement `poll`. Use `getWorkflowStaticData('node')` to persist state. Example: `nodes/Google/Gmail/GmailTrigger.node.ts`
27- **Generic triggers**: Implement `trigger` function. Example: `nodes/MQTT/MqttTrigger.node.ts`
28 
29## Node Parameters
30 
31Common parameter types:
32- `string` - Text input
33- `options` - Dropdown (static or dynamic via `loadOptionsMethod`)
34- `resourceLocator` - Select by list, ID, or URL
35- `collection` - Key-value pairs
36- `fixedCollection` - Structured collections
37 
38Use `displayOptions` to show/hide fields based on other parameters. Use `noDataExpression: true` for resource/operation selectors.
39 
40## Versioning
41 
42- **Light versioning**: Use version arrays in description: `version: [3, 3.1, 3.2]`
43- **Full versioning**: Use `VersionedNodeType` class with separate version implementations. Example: `nodes/Set/Set.node.ts`
44 
45## Credentials
46 
47Credentials are defined in `credentials/` directory and implement `ICredentialType`:
48- `name` - Internal identifier
49- `displayName` - Human-readable name
50- `properties` - Credential fields
51- `authenticate` - Authentication configuration (generic or custom function)
52- `test` - Credential test request
53 
54Nodes can test credentials via `methods.credentialTest`.
55 
56## Testing
57 
58### Unit Tests
59- Use `vitest-mock-extended` for mocking interfaces
60- Use `nock` for HTTP mocking
61- Mock all external dependencies
62- Test happy paths, error handling, edge cases, and binary data
63 
64### Workflow Tests
65- Use `NodeTestHarness` with JSON workflow definitions
66- Mock external APIs with nock
67- Use `pnpm test` for running tests. Example: `cd packages/nodes-base/ && pnpm test TestFileName`
68 
69## Common Development Tasks
70 
71### Creating a New Node
721. Create directory: `nodes/YourService/`
732. Create `YourService.node.ts` implementing `INodeType`
743. Add icon SVG files in node directory
754. Define credentials in `credentials/` if needed
765. Write tests following testing guidelines
776. Register in `package.json` nodes array if needed
78 
79### Adding Dynamic Options
80Add `loadOptionsMethod` to parameter's `typeOptions` and implement method in `methods.loadOptions`.
81 
82### Adding Resource Locator
83Change parameter type to `'resourceLocator'`, define modes (list, id, url), add `searchListMethod` for list mode, add `extractValue` regex for URL mode.
84 
85## Best Practices
86 
87### TypeScript
88- Never use `any` type - use proper types or `unknown`
89- Avoid type casting with `as` - use type guards instead
90- Define interfaces for API responses
91 
92### Error Handling
93- Use `NodeOperationError` for user-facing errors
94- Use `NodeApiError` for API-related errors
95- Support `continueOnFail` option when appropriate
96 
97### Security
98 
99User input is untrusted. In nodes it arrives mainly through
100`this.getNodeParameter(...)` (and incoming `item.json`), and a workflow author
101controls these values.
102 
103**Never use an untrusted value as a computed object key in an assignment.** A
104value such as `__proto__`, `constructor`, or `prototype` pollutes the prototype
105chain:
106 
107```ts
108// UNSAFE — `table`/`key` come from this.getNodeParameter(...)
109if (acc[table] === undefined) acc[table] = {};
110acc[table][key] = value;
111```
112 
113Route dynamic-key writes through the `n8n-workflow` helpers, or build the
114accumulator as a `Map` / `Object.create(null)`:
115 
116```ts
117import { setSafeObjectProperty, isSafeObjectProperty } from 'n8n-workflow';
118 
119if (isSafeObjectProperty(table) && acc[table] === undefined) {
120	setSafeObjectProperty(acc, table, {});
121}
122```
123 
124This only applies to dynamic-key **writes** (grouping/aggregating rows by a
125user-chosen column is the common case). Reads like `const x = obj[key]` are
126safe. Reference usage: `nodes/Google/GSuiteAdmin/GSuiteAdmin.node.ts`.
127 
128### Code Organization
129- Separate operation/field descriptions into separate files
130- Create reusable API request helpers in GenericFunctions
131- Use kebab-case for files, PascalCase for classes
132 
133### UI/UX
134- Use clear `displayName` and `description` fields
135- Set sensible default values
136- Use `displayOptions` to show/hide fields conditionally
137 
138## Example Nodes
139 
140- Declarative: `nodes/Okta/Okta.node.ts`
141- Programmatic: `nodes/Discord/v2/DiscordV2.node.ts`
142- Webhook Trigger: `nodes/Microsoft/Teams/MicrosoftTeamsTrigger.node.ts`
143- Polling Trigger: `nodes/Google/Gmail/GmailTrigger.node.ts`
144- Generic Trigger: `nodes/MQTT/MqttTrigger.node.ts`
145- Versioned: `nodes/Set/Set.node.ts`
146