From 3fef5f751f1b88fcab06f69dfee6ae2a8563cfa8 Mon Sep 17 00:00:00 2001 From: David Arens Date: Mon, 12 May 2025 17:03:39 +0200 Subject: [PATCH] Initial draft for verified community nodes docs (#3100) Co-authored-by: Justin Ellingwood --- .../integrations/submit-community-node.md | 13 + .../environment-variables/nodes.md | 5 +- .../installation/gui-install.md | 11 +- .../community-nodes/installation/index.md | 11 +- .../installation/manual-install.md | 4 +- .../installation/verified-install.md | 35 +++ docs/integrations/community-nodes/risks.md | 8 +- .../community-nodes/troubleshooting.md | 4 + .../creating-nodes/build/reference/index.md | 1 + .../build/reference/ux-guidelines.md | 251 ++++++++++++++++++ .../reference/verification-guidelines.md | 39 +++ docs/integrations/creating-nodes/overview.md | 2 +- nav.yml | 3 + styles/config/vocabularies/default/accept.txt | 2 +- 14 files changed, 373 insertions(+), 16 deletions(-) create mode 100644 docs/integrations/community-nodes/installation/verified-install.md create mode 100644 docs/integrations/creating-nodes/build/reference/ux-guidelines.md create mode 100644 docs/integrations/creating-nodes/build/reference/verification-guidelines.md diff --git a/_snippets/integrations/submit-community-node.md b/_snippets/integrations/submit-community-node.md index f8f7cf6e4..926406a10 100644 --- a/_snippets/integrations/submit-community-node.md +++ b/_snippets/integrations/submit-community-node.md @@ -1,6 +1,7 @@ /// note | Subject to change The standards described in this document are for the first release of the community nodes repository. These may change in future releases. /// + Community nodes are npm packages, hosted in the npm registry. When building a node to submit to the community node repository, use the following resources to make sure your node setup is correct: @@ -19,3 +20,15 @@ To make your node available to the n8n community node repository, you must: * Check your node using the [linter](/integrations/creating-nodes/test/node-linter.md) and test it locally to ensure it works. * Submit the package to the npm registry. Refer to npm's documentation on [Contributing packages to the registry](https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry){:target=_blank .external-link} for more information. +## Submit your node for verification by n8n + +n8n vets verified community nodes. Users can discover and install verified community nodes from the nodes panel in n8n. These nodes need to adhere to certain technical and UX standards and constraints. + +Before submitting your node for review by n8n, you must: + +* Make sure that your node follows the [technical guidelines for verified community nodes](/integrations/creating-nodes/build/reference/verification-guidelines.md) and that all automated checks pass. Specifically, verified community nodes aren't allowed to use any run-time dependencies. +* Ensure that your node follows the [UX guidelines](/integrations/creating-nodes/build/reference/ux-guidelines.md). +* Make sure that the node has appropriate documentation in the form of a README in the [npm package](https://docs.npmjs.com/about-package-readme-files) or a related public repository. +* Submit your node to npm as n8n will fetch it from there for final vetting. + +If your node meets all the above requirements, [click here to submit your node for verification](https://internal.users.n8n.cloud/form/f0ff9304-f34a-420e-99da-6103a2f8ac5b). diff --git a/docs/hosting/configuration/environment-variables/nodes.md b/docs/hosting/configuration/environment-variables/nodes.md index 3ac56d37c..de2520f14 100644 --- a/docs/hosting/configuration/environment-variables/nodes.md +++ b/docs/hosting/configuration/environment-variables/nodes.md @@ -24,5 +24,8 @@ This page lists the environment variables configuration options for managing [no | `NODE_FUNCTION_ALLOW_EXTERNAL` | String | - | Permit users to import specific external modules (from `n8n/node_modules`) in the Code node. n8n disables importing modules by default. | | `NODES_ERROR_TRIGGER_TYPE` | String | `n8n-nodes-base.errorTrigger` | Specify which node type to use as Error Trigger. | | `N8N_CUSTOM_EXTENSIONS` | String | - | Specify the path to directories containing your custom nodes. | -| `N8N_COMMUNITY_PACKAGES_ENABLED` | Boolean | `true` | Enables (true) or disables (false) community nodes. | +| `N8N_COMMUNITY_PACKAGES_ENABLED` | Boolean | `true` | Enables (true) or disables (false) the functionality to install and load community nodes. If set to false, neither verified nor unverified community packages will be available, regardless of their individual settings. | | `N8N_COMMUNITY_PACKAGES_REGISTRY` | String | `https://registry.npmjs.org` | NPM registry URL to pull community packages from (license required). | +| `N8N_VERIFIED_PACKAGES_ENABLED` | Boolean | `true` | When `N8N_COMMUNITY_PACKAGES_ENABLED` is true, this variable controls whether to show verified community nodes in the nodes panel for installation and use (true) or to hide them (false). | +| `N8N_UNVERIFIED_PACKAGES_ENABLED` | Boolean | `true` | When `N8N_COMMUNITY_PACKAGES_ENABLED` is true, this variable controls whether to enable the installation and use of unverified community nodes from an NPM registry (true) or not (false). | +| `N8N_COMMUNITY_PACKAGES_PREVENT_LOADING` | Boolean | `false` | Prevents (true) or allows (false) loading installed community nodes on instance startup. Use this if a faulty node prevents the instance from starting. | diff --git a/docs/integrations/community-nodes/installation/gui-install.md b/docs/integrations/community-nodes/installation/gui-install.md index 3b5635af0..ffdce7e9b 100644 --- a/docs/integrations/community-nodes/installation/gui-install.md +++ b/docs/integrations/community-nodes/installation/gui-install.md @@ -3,14 +3,17 @@ contentType: howto --- -# Install community nodes in the n8n app +# Install community nodes from npm in the n8n app -/// note | Limited to n8n instance owners -Only the n8n instance owner can install and manage community nodes. The instance owner is the person who sets up and manages user management. +/// note | Only for instance owners of self-hosted n8n instances +Only the n8n instance owner of a self-hosted n8n instance can install and manage community nodes from npm. The instance owner is the person who sets up and manages user management. + +Admin accounts can also uninstall any community node, verified or unverified. This helps them remove problematic nodes that may affect the instance's health and functionality. /// + ## Install a community node -To install a community node: +To install a community node from npm: 1. Go to **Settings** > **Community Nodes**. 2. Select **Install**. diff --git a/docs/integrations/community-nodes/installation/index.md b/docs/integrations/community-nodes/installation/index.md index 76ccdf536..cea3f9de3 100644 --- a/docs/integrations/community-nodes/installation/index.md +++ b/docs/integrations/community-nodes/installation/index.md @@ -5,11 +5,12 @@ contentType: overview # Install and manage community nodes -There are two ways to install community nodes: +There are three ways to install community nodes: -* Within n8n [using the GUI](/integrations/community-nodes/installation/gui-install.md). -* [Manually from the command line](/integrations/community-nodes/installation/manual-install.md): use this method if your n8n instance doesn't support installation through the in-app GUI. +* Within n8n using the [nodes panel](/integrations/community-nodes/installation/verified-install.md) (for verified community nodes only). +* Within n8n [using the GUI](/integrations/community-nodes/installation/gui-install.md): Use this method to install community nodes from the npm registry. +* [Manually from the command line](/integrations/community-nodes/installation/manual-install.md): use this method to install community nodes from npm if your n8n instance doesn't support installation through the in-app GUI. -/// note | Only available on self-hosted instances -Community nodes aren't available on n8n cloud and require [self-hosting](/hosting/index.md) n8n. +/// note | Installing from npm only available on self-hosted instances +Unverified community nodes aren't available on n8n cloud and require [self-hosting](/hosting/index.md) n8n. /// diff --git a/docs/integrations/community-nodes/installation/manual-install.md b/docs/integrations/community-nodes/installation/manual-install.md index 9d9f09bd0..89f2f6b27 100644 --- a/docs/integrations/community-nodes/installation/manual-install.md +++ b/docs/integrations/community-nodes/installation/manual-install.md @@ -3,9 +3,9 @@ contentType: howto --- -# Manually install community nodes +# Manually install community nodes from npm -You can manually install community nodes on self-hosted n8n. +You can manually install community nodes from the npm registry on self-hosted n8n. You need to manually install community nodes in the following circumstances: diff --git a/docs/integrations/community-nodes/installation/verified-install.md b/docs/integrations/community-nodes/installation/verified-install.md new file mode 100644 index 000000000..fa06fe860 --- /dev/null +++ b/docs/integrations/community-nodes/installation/verified-install.md @@ -0,0 +1,35 @@ +--- +#https://www.notion.so/n8n/Frontmatter-432c2b8dff1f43d4b1c8d20075510fe4 +contentType: howto +--- + +# Install verified community nodes in the n8n app + +/// note | Limited to n8n instance owners +Only the n8n instance owner can install and manage verified community nodes. The instance owner is the person who sets up and manages user management. All members of an n8n instance can use already installed community nodes in their workflows. + +Admin accounts can also uninstall any community node, verified or unverified. This helps them remove problematic nodes that may affect the instance's health and functionality. +/// + +## Install a community node + +To install a [verified community node](/integrations/creating-nodes/deploy/submit-community-nodes.md#submit-your-node-for-verification-by-n8n): + +1. Go to the **Canvas** and open the **nodes panel** (either by selecting '+' or pressing ++tab++). +2. **Search** for the node that you're looking for. If there is a matching verified community node, you will see a **More from the community** section at the bottom of the nodes panel. +3. Select the node you want to install. This takes you to a detailed view of the node, showing all the supported actions. +4. Select **install**. This will install the node for your instance and enable all members to use it in their workflows. +5. You can now add the node to your workflows. + +/// note | Enable installation of verified community nodes +Some users may not want to show verified community nodes in the nodes panel of their instances. On n8n cloud, instance owners can toggle this in the [Cloud Admin Panel](/manage-cloud/cloud-admin-dashboard.md). Self-hosted users can use [environment variables](/hosting/configuration/environment-variables/nodes.md) to control the availability of this feature. +/// + +## Uninstall a community node + +To uninstall a community node: + +1. Go to **Settings** > **Community nodes**. +2. On the node you want to install, select **Options** ![Three dots options menu](/_images/common-icons/three-dot-options-menu.png){.off-glb}. +3. Select **Uninstall package**. +4. Select **Uninstall Package** in the confirmation modal. diff --git a/docs/integrations/community-nodes/risks.md b/docs/integrations/community-nodes/risks.md index 9125168be..414b5ce94 100644 --- a/docs/integrations/community-nodes/risks.md +++ b/docs/integrations/community-nodes/risks.md @@ -5,7 +5,7 @@ contentType: explanation # Risks when using community nodes -Using community nodes means you are installing unverified code from a public source into your n8n instance. This has some risks. +Installing community nodes from npm means you are installing unverified code from a public source into your n8n instance. This has some risks. Risks include: @@ -13,6 +13,10 @@ Risks include: * Data security: any community node that you use has access to data in your workflows. * Breaking changes: node developers may introduce breaking changes in new versions of their nodes. A breaking change is an update that breaks previous functionality. Depending on the node versioning approach that a node developer chooses, upgrading to a version with a breaking change could cause all workflows using the node to break. Be careful when upgrading your nodes. +/// note | n8n vets verified community nodes +In addition to publicly available community nodes from npm, n8n inspects some nodes and makes them available as [verified community node inside the nodes panel](/integrations/community-nodes/installation/verified-install.md). These nodes have to meet a set of data and system security requirements for approval. +/// + ## Report bad community nodes @@ -23,4 +27,4 @@ You can report bad community nodes to [security@n8n.io](mailto: security@n8n.io) ## Disable community nodes -You can disable community nodes by setting `N8N_COMMUNITY_PACKAGES_ENABLED` to `false`. +If you are self-hosting n8n, you can disable community nodes by setting `N8N_COMMUNITY_PACKAGES_ENABLED` to `false`. On n8n cloud, visit the [Cloud Admin Panel](https://docs.n8n.io/manage-cloud/cloud-admin-dashboard/) and disable community nodes from there. See [troubleshooting](/integrations/community-nodes/troubleshooting.md) for more information. diff --git a/docs/integrations/community-nodes/troubleshooting.md b/docs/integrations/community-nodes/troubleshooting.md index 1bd476e40..7dfd90aa7 100644 --- a/docs/integrations/community-nodes/troubleshooting.md +++ b/docs/integrations/community-nodes/troubleshooting.md @@ -15,3 +15,7 @@ If running n8n using Docker: depending on your Docker setup, you may lose the pa * Set the `N8N_REINSTALL_MISSING_PACKAGES` environment variable to `true`. The second option might increase startup time and may cause health checks to fail. + +## Prevent loading community nodes on n8n cloud + +If your n8n cloud instance crashes and fails to start, you can prevent installed community nodes from loading on instance startup. Visit the [Cloud Admin Panel](/manage-cloud/cloud-admin-dashboard.md) > **Manage** and toggle **Disable all community nodes** to **`true`**. This toggle is only visible when you allow community node installation. diff --git a/docs/integrations/creating-nodes/build/reference/index.md b/docs/integrations/creating-nodes/build/reference/index.md index 2724d6915..09030b59b 100644 --- a/docs/integrations/creating-nodes/build/reference/index.md +++ b/docs/integrations/creating-nodes/build/reference/index.md @@ -10,3 +10,4 @@ This section contains reference information, including details about: * [Node UI elements](/integrations/creating-nodes/build/reference/ui-elements.md) * [Organizing your node files](/integrations/creating-nodes/build/reference/node-file-structure.md) * Key parameters in your node's [base file](/integrations/creating-nodes/build/reference/node-base-files/index.md) and [credentials file](/integrations/creating-nodes/build/reference/credentials-files.md). +* [UX guidelines](/integrations/creating-nodes/build/reference/ux-guidelines.md) and [verification guidelines](/integrations/creating-nodes/build/reference/verification-guidelines.md) for submitting your node for [verification by n8n](/integrations/community-nodes/installation/verified-install.md). diff --git a/docs/integrations/creating-nodes/build/reference/ux-guidelines.md b/docs/integrations/creating-nodes/build/reference/ux-guidelines.md new file mode 100644 index 000000000..755211d55 --- /dev/null +++ b/docs/integrations/creating-nodes/build/reference/ux-guidelines.md @@ -0,0 +1,251 @@ +--- +#https://www.notion.so/n8n/Frontmatter-432c2b8dff1f43d4b1c8d20075510fe4 +contentType: reference +--- + +# UX guidelines for community nodes + +Your node's UI must conform to these guidelines to be a [verified community node](/integrations/creating-nodes/deploy/submit-community-nodes.md#submit-your-node-for-verification-by-n8n) candidate. + +## Credentials + +API key and sensitive credentials should always be password fields. + +### OAuth + +Always include the OAuth credential if available. + +## Node structure + +### Operations to include + +Try to include **CRUD** operations for each resource type. + +Try to include common operations in nodes for each resource. n8n uses some CRUD operations to keep the experience consistent and allow users to perform basic operations on the resource. The suggested operations are: + +* **Create** +* **Create or Update (Upsert)** +* **Delete** +* **Get** +* **Get Many:** also used when some filtering or search is available +* **Update** + +Notes: + +1. These operations can apply to the resource itself or an entity inside of the resource (for example, a row inside a Google Sheet). When operating on an entity inside of the resource, you must specify the **name of the entity** in the operations name. +2. The naming could change depending on the node and the resource. Check the following guidelines for details. + +### Resource Locator + +* Use a Resource Locator component whenever possible. This provides a much better UX for users. The Resource Locator Component is most often useful when you have to select a single item. +* The default option for the Resource Locator Component should be `From list` (if available). + +### Consistency with other nodes + +* Maintain UX consistency: n8n tries to keep its UX consistent. This means following existing UX patterns, in particular, those used in the latest new or overhauled nodes. +* Check similar nodes: For example, if you're working on a database node, it's worth checking the Postgres node. + +### Sorting options + +* You can enhance certain "Get Many" operations by providing users with sorting options. +* Add sorting in a dedicated collection (below the "Options" collection). Follow the example of [Airtable Record:Search](https://github.com/n8n-io/n8n/blob/92e2a8e61a4189025e5d4bac8be81576b624fe85/packages/nodes-base/nodes/Airtable/v2/actions/record/search.operation.ts#L85-L135). + +## Node functionality + +### Deleting operations output + +When deleting an item (like a record or a row), return an array with a single object: `{"deleted": true}`. This is a confirmation for the user that the deletion was successful and the item will trigger the following node. + +### Simplifying output fields + +#### Normal nodes: 'Simplify' parameter + +When an endpoint returns data with more than 10 fields, add the "Simplify" boolean parameter to return a simplified version of the output with max 10 fields. + +* One of the main issues with n8n can be the size of data and the Simplify parameter limits that problem by reducing data size. +* Select the most useful fields to output in the simplified node and sort them to have the most used ones at the top. +* In the Simplify mode, it's often best to flatten nested fields +* Display Name: `Simplify` +* Description: `Whether to return a simplified version of the response instead of the raw data` + +#### AI tool nodes: ‘Output’ parameter + +When an endpoint returns data with more than 10 fields, add the 'Output' option parameter with 3 modes. + +In AI tool nodes, allow the user to be more granular and select the fields to output. The rationale is that tools may run out of context window and they can get confused by too many fields, so it's better to pass only the ones they need. + +Options: + +* **Simplified:** Works the same as the "Simplify" parameter described above. +* **Raw:** Returns all the available fields. +* **Selected fields:** Shows a multi-option parameter for selecting the fields to add to the output and send to the AI agent. By default, this option always returns the ID of the record/entity. + +## Copy + +### Text Case + +Use **Title Case** for the node `name`, `parameters display names` (labels), `dropdown titles`. Title Case is when you capitalize the first letter of each word, except for certain small words, such as articles and short prepositions. + +Use **Sentence case** for node `action` names, node `descriptions`, `parameters descriptions` (tooltips), `hints`, `dropdown descriptions`. + +### Terminology + +* **Use the third-party service terminology:** Try to use the same terminology as the service you're interfacing with (for example, Notion 'blocks', not Notion 'paragraphs'). +* **Use the terminology used in the UI:** Stick to the terminology used in the user interface of the service, rather than that used in the APIs or technical documentation (for example, in Trello you "archive" cards, but in the API they show up as "closed". In this case, you might want to use "archive"). +* **No tech jargon:** Don't use technical jargon where simple words will do. For example, use "field" instead of "key". +* **Consistent naming:** Choose one term for something and stick to it. For example, don't mix "directory" and "folder". + +### Placeholders + +It's often helpful to insert examples of content in parameters placeholders. These should start with "e.g." and use **camel case** for the demo content in fields. + +Placeholder examples to copy: + +* image: `e.g. https://example.com/image.png` +* video: `e.g. https://example.com/video.mp4` +* search term: `e.g. automation` +* email: `e.g. nathan@example.com` +* Twitter user (or similar): `e.g. n8n` +* Name and last name: `e.g. Nathan Smith` +* First name: `e.g. Nathan` +* Last name: `e.g. Smith` + +### Operations name, action, and description + +* **Name:** This is the name displayed in the select when the node is open on the canvas. It must use title case and doesn't have to include the resource (for example, "Delete"). +* **Action:** This is the name of the operation displayed in the panel where the user selects the node. It must be in sentence case and must include the resource (for example, "Delete record"). +* **Description:** This is the sub-text displayed below the name in the select when the node is open on the canvas. It must use sentence case and must include the resource. It can add a bit of information and use alternative words than the basic resource/operation (for example, "Retrieve a list of users"). +* If the operation acts on an entity that's not the Resource (for example, a row in a Google Sheet), specify that in the operation name (for example, "Delete Row"). + +As a general rule, is important to understand what the **object** of an operation is. Sometimes, the object of an Operation is the resource itself (for example, `Sheet:Delete` to delete a Sheet). + +In other cases, the object of the operation isn't the resource, but something contained inside the resource (for example, `Table:Delete rows`, here the resource is the table, but what you are operating on are the rows inside of it). + +#### Naming `name` + +This is the name displayed in the select when the node is open on the canvas. + +* Parameter: `name` +* Case: Title Case + +Naming guidelines: + +* **Don't repeat the resource (if the resource selection is above):** The resource is often displayed above the operation, so it's not necessary to repeat it in the operation (this is the case if the object of the operation is the resource itself). + * For example: `Sheet:Delete` → No need to repeat `Sheet` in `Delete`, because n8n displays `Sheet` in the field above and what you're deleting is the Sheet. +* **Specify the resource if there's no resource selection above:** In some nodes, you won't have a resource selection (because there's only one resource). In these cases, specify the resource in the operation. + * For example: `Delete Records` → In Airtable, there's no resource selection, so it's better to specify that the Delete operation will delete records. +* **Specify the object of the operation if it's not the resource:** Sometimes, the object of the operation isn't the resource. In these cases, specify the object in the operation as well. + * For example: `Table:Get Columns` → Specify `Columns` because the resource is `Table`, while the object of the operation is `Columns`. + +#### Naming `action` + +This is the name of the operation displayed in the panel where the user selects the node. +* Parameter: `action` +* Case: Sentence case + +Naming guidelines: + +* **Omit articles:** To keep the text shorter, get rid of articles (a, an, the…). + * **correct**: `Update row in sheet` + * **incorrect**: `Update a row in a sheet` +* **Repeat the resource:** In this case, it's okay to repeat the resource. Even if the resource is visible in the list, the user might not notice and it's useful to repeat it in the operation label. +* **Specify the object of the operation if it is not the resource:** Same as for the operation name. In this case, you don't need to repeat the resource. + * For example: `Append Rows` → You have to specify `Rows` because rows are what you're actually appending to. Don't add the resource (`Sheet`) since you aren't appending to the resource. + +#### Naming `description` + +This is the subtext displayed below the name in the selection when the node is open on the canvas. + +* Parameter: `description` +* Case: Sentence case + +Naming guidelines: + +* If possible, add more information than that specified in the operation `name` +* Use alternative wording to help users better understand what the operation is doing. Some people might not understand the text used in the operation (maybe English isn't their native language), and using alternative working could help them. + +#### Vocabulary + +n8n uses a general vocabulary and some context-specific vocabulary for groups of similar applications (for example, databases or spreadsheets). + +The general vocabulary takes inspiration from CRUD operations: + +* **Clear** + * Delete all the contents of the resource (empty the resource). + * Description: `Delete all the s inside the ` +* **Create** + * Create a new instance of the resource. + * Description: `Create a new ` +* **Create or Update** + * Create or update an existing instance of the resource. + * Description: `Create a new or update an existing one (upsert)` +* **Delete** + * You can use "Delete" in two different ways: + 1. Delete a resource: + * Description: `Delete a permanently` (use "permanently" only if that's the case) + 2. Delete something **inside** of the resource (for example, a row): + * In this case, **always specify the object of the operation**: for example, `Delete Rows` or `Delete Records`. + * Description: `Delete a permanently` +* **Get** + * You can use "Get" in two different ways: + 1. Get a resource: + * Description: `Retrieve a ` + 2. Get an item **inside** of the resource (for example, records): + * In this case, **always specify the object of the operation**: for example, `Get Row` or `Get Record`. + * Description: `Retrieve a from the/a ` +* **Get Many** + * You can use "Get Many" in two different ways: + 1. Get a list of resources (without filtering): + * Description: `Retrieve a list of s` + 2. Get a list of items **inside** of the resource (for example, records): + * In this case, **always specify the object of the operation**: for example, `Get Many Rows` or `Get Many Records`. + * You can omit `Many`: `Get Many Rows` can be `Get Rows`. + * Description: `List all s in the/a ` +* **Insert** or **Append** + * Add something inside of a resource. + * Use `insert` for database nodes. + * Description: `Insert (s) in a ` +* **Insert or Update** or **Append or Update** + * Add or update something inside of a resource. + * Use `insert` for database nodes. + * Description: `Insert (s) or update an existing one(s) (upsert)` +* **Update** + * You can use "Update" in two different ways: + 1. Update a resource: + * Description: `Update one or more s` + 2. Update something **inside** of a resource (for example, a row): + * In this case, **always specify the object of the operation**: for example, `Update Rows` or `Update Records`. + * Description: `Update (s) inside a ` + +### Referring to parameter and field name + +When you need to refer to parameter names or field names in copy, wrap them in single quotation marks (for example, "Please fill the `'name'` parameter). + +### Boolean description + +Start the description of boolean components with 'Whether...' + +## Errors + +### General philosophy + +Errors are sources of pain for users. For this reason, n8n always wants to tell the user: + +* **What happened**: a description of the error and what went wrong. +* **How to solve the problem**: or at least how to get unstuck and continue using n8n without problems. n8n doesn't want users to remain blocked, so use this as an opportunity to guide them to success. + +### Error structure in the Output panel + +#### Error Message - What happened + +This message explains to the user what happened, and the current issue that prevents the execution completing. + +* If you have the `displayName` of the parameter that triggered the error, include it in the error message or description (or both). +* Item index: if you have the ID of the item that triggered the error, append `[Item X]` to the error message. For example, `The ID of the release in the parameter “Release ID” for could not be found [item 2]`. +* Avoid using words like "error", "problem", "failure", "mistake". + +#### Error Description - How to solve or get unstuck + +The description explains to users how to solve the problem, what to change in the node configuration (if that's the case), or how to get unstuck. Here, you should guide them to the next step and unblock them. + +Avoid using words like "error", "problem", "failure", "mistake". diff --git a/docs/integrations/creating-nodes/build/reference/verification-guidelines.md b/docs/integrations/creating-nodes/build/reference/verification-guidelines.md new file mode 100644 index 000000000..3d71f9600 --- /dev/null +++ b/docs/integrations/creating-nodes/build/reference/verification-guidelines.md @@ -0,0 +1,39 @@ +--- +#https://www.notion.so/n8n/Frontmatter-432c2b8dff1f43d4b1c8d20075510fe4 +contentType: reference +--- + +# Community node verification guidelines + +/// note | Do you want n8n to verify your node? +Consider following these guidelines while building your node if you want to submit it for verification by n8n. Any user with verified community nodes enabled can discover and install verified nodes from n8n's nodes panel. +/// + +## Package source verification + +* Verify that your npm package repository URL matches the expected GitHub (or other platform) repository. +* Confirm that the package author / maintainer matches between npm and the repository. +* Confirm that the git link in npm works and that the repository is public. +* Make sure your package has proper documentation (README, usage examples, etc.). +* Make sure your package license is MIT. + +## No external dependencies + +* Ensure that your package does **not** include any external dependencies to keep it lightweight and easy to maintain. + +## Proper documentation + +* Provide clear documentation, whether it’s a **README** on GitHub or links to relevant **API documentation**. +* Include usage instructions, example workflows, and any necessary authentication details. + +## No access to environment variables or file system + +* The code **must not** interact with environment variables or attempt to read/write files. +* Pass all necessary data through node parameters. + +## Follow n8n best practices + +* Maintain a clear and consistent coding style. +* Use **TypeScript** and follow n8n's [**node development guidelines**](/integrations/creating-nodes/overview.md). +* Ensure proper error handling and validation. +* Make sure the linter passes (in other words, make sure running `npx @n8n/scan-community-package n8n-nodes-PACKAGE` passes). diff --git a/docs/integrations/creating-nodes/overview.md b/docs/integrations/creating-nodes/overview.md index 73a87cde5..d145786b3 100644 --- a/docs/integrations/creating-nodes/overview.md +++ b/docs/integrations/creating-nodes/overview.md @@ -12,7 +12,7 @@ This section includes: * Guidance on planning your build, including [which style to use](/integrations/creating-nodes/plan/choose-node-method.md). * [Tutorials](/integrations/creating-nodes/build/index.md) for different node building styles. * Instructions for [testing your node](/integrations/creating-nodes/test/index.md), including how to use the n8n [node linter](/integrations/creating-nodes/test/node-linter.md) and [troubleshooting](/integrations/creating-nodes/test/troubleshooting-node-development.md) support. -* How to [share your node](/integrations/creating-nodes/deploy/submit-community-nodes.md) with the community, or use it as a [private node](/integrations/creating-nodes/deploy/install-private-nodes.md). +* How to [share your node](/integrations/creating-nodes/deploy/submit-community-nodes.md) with the community, submit it for [verification by n8n](/integrations/creating-nodes/deploy/submit-community-nodes.md), or use it as a [private node](/integrations/creating-nodes/deploy/install-private-nodes.md). * [Reference material](/integrations/creating-nodes/build/reference/index.md), including UI elements and information on the individual files that make up a node. ## Prerequisites diff --git a/nav.yml b/nav.yml index 7084cf04c..e56d11b63 100644 --- a/nav.yml +++ b/nav.yml @@ -1084,6 +1084,7 @@ nav: - Community nodes: - Installation and management: - integrations/community-nodes/installation/index.md + - Install verified community nodes: integrations/community-nodes/installation/verified-install.md - GUI installation: integrations/community-nodes/installation/gui-install.md - Manual installation: integrations/community-nodes/installation/manual-install.md - Risks: integrations/community-nodes/risks.md @@ -1121,6 +1122,8 @@ nav: - Credentials files: integrations/creating-nodes/build/reference/credentials-files.md - HTTP request helpers: integrations/creating-nodes/build/reference/http-helpers.md - Item linking: integrations/creating-nodes/build/reference/paired-items.md + - UX guidelines: integrations/creating-nodes/build/reference/ux-guidelines.md + - Verification guidelines: integrations/creating-nodes/build/reference/verification-guidelines.md - Test your node: - integrations/creating-nodes/test/index.md - Run your node locally: integrations/creating-nodes/test/run-node-locally.md diff --git a/styles/config/vocabularies/default/accept.txt b/styles/config/vocabularies/default/accept.txt index ceadf4912..9cdb12c7d 100644 --- a/styles/config/vocabularies/default/accept.txt +++ b/styles/config/vocabularies/default/accept.txt @@ -228,7 +228,7 @@ There are [Tt]imesheet Todoist Toggl -[Tt]ooltip +[Tt]ooltips? [Tt]ouchpad Traefik Trellix