Merge c869ae7789 into 67ee5b8e80

.devcontainer/devcontainer.json

@@ -0,0 +1,22 @@
+{
+  "name": "Custom n8n Node Development",
+  "image": "mcr.microsoft.com/devcontainers/javascript-node:20",
+  "features": {
+    "ghcr.io/devcontainers/features/docker-in-docker:2": {},
+    "ghcr.io/devcontainers/features/git:1": {},
+    "ghcr.io/devcontainers/features/github-cli:1": {},
+    "ghcr.io/devcontainers-extra/features/n8n:1": {}
+  },
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-vscode.vscode-typescript-next",
+        "esbenp.prettier-vscode",
+        "ms-vscode.vscode-eslint"
+      ]
+    }
+  },
+  "forwardPorts": [3000, 5678],
+  "postCreateCommand": "bash start-n8n-with-custom-node.sh",
+  "remoteUser": "node"
+}

README.md

@@ -1,48 +1,94 @@
 ![Banner image](https://user-images.githubusercontent.com/10284570/173569848-c624317f-42b1-45a6-ab09-f0ea3c247648.png)
 
-# n8n-nodes-starter
+n8n-nodes-starter
+=================
 
-This repo contains example nodes to help you get started building your own custom integrations for [n8n](https://n8n.io). It includes the node linter and other dependencies.
+This repo is a template to start building your own custom integrations for [n8n](https://n8n.io).
 
-To make your custom node available to the community, you must create it as an npm package, and [submit it to the npm registry](https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry).
+It contains instructions for how to develop your own custom nodes, as well as publishing them so others in the n8n community can use them.
 
-If you would like your node to be available on n8n cloud you can also [submit your node for verification](https://docs.n8n.io/integrations/creating-nodes/deploy/submit-community-nodes/).
+For a comprehensive guide on creating your nodes, see [this page in the documentation](https://docs.n8n.io/integrations/creating-nodes/overview/).
 
-## Prerequisites
+Getting started
-
+---------------
-You need the following installed on your development machine:
+First, you'll need to make your own copy of this repo:
-
-* [git](https://git-scm.com/downloads)
-* Node.js and npm. Minimum version Node 20. You can find instructions on how to install both using nvm (Node Version Manager) for Linux, Mac, and WSL [here](https://github.com/nvm-sh/nvm). For Windows users, refer to Microsoft's guide to [Install NodeJS on Windows](https://docs.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-windows).
-* Install n8n with:
-  ```
-  npm install n8n -g
-  ```
-* Recommended: follow n8n's guide to [set up your development environment](https://docs.n8n.io/integrations/creating-nodes/build/node-development-environment/).
-
-## Using this starter
-
-These are the basic steps for working with the starter. For detailed guidance on creating and publishing nodes, refer to the [documentation](https://docs.n8n.io/integrations/creating-nodes/).
 
 1. [Generate a new repository](https://github.com/n8n-io/n8n-nodes-starter/generate) from this template repository.
-2. Clone your new repo:
+1. Install [git](https://git-scm.com/downloads), if you don't have it already
+1. Clone this repo to your local machine:
    ```
    git clone https://github.com/<your organization>/<your-repo-name>.git
    ```
-3. Run `npm i` to install dependencies.
+
-4. Open the project in your editor.
+Second, you'll need to prepare your environment to develop on the nodes in this repository. This means:
-5. Browse the examples in `/nodes` and `/credentials`. Modify the examples, or replace them with your own nodes.
+
-6. Update the `package.json` to match your details.
+- Installing `npm`
-7. Run `npm run lint` to check for errors or `npm run lintfix` to automatically fix errors when possible.
+- Building the nodes in this repository
-8. Test your node locally. Refer to [Run your node locally](https://docs.n8n.io/integrations/creating-nodes/test/run-node-locally/) for guidance.
+- Getting a running n8n instance
-9. Replace this README with documentation for your node. Use the [README_TEMPLATE](README_TEMPLATE.md) to get started.
+- Linking your nodes into the running n8n instance
-10. Update the LICENSE file to use your details.
+
+You can do this in one of two ways:
+
+### Option 1: Use the devcontainer (recommended)
+This repo has [a VSCode devcontainer spec](.devcontainer/devcontainer.json) with all the tooling you need to work on your custom nodes in a Docker container sandbox.
+
+To use:
+
+1. Install [Docker](https://www.docker.com/) and start it
+1. [Install VSCode](https://code.visualstudio.com/)
+1. Install the VSCode [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
+1. Open your local clone of this repository
+1. Choose "Reopen in Container" when the popup appears saying, "Folder contains a Dev Container configuration file. Reopen folder to develop in a container?"
+1. Wait for the container to build and open
+1. Visit [localhost:5678](http://localhost:5678/) to open the n8n instance running inside the devcontainer
+1. In a workflow, for "Example Node" to ensure that the nodes in this repo are being picked up properly
+
+### Option 2: Bring your own environment
+You can also bring your own environment. 
+
+To start, you'll need to follow [this guide for setting up your local n8n development environment](https://docs.n8n.io/integrations/creating-nodes/build/node-development-environment/).
+
+Then you'll need to link your node into your running n8n instance using [these steps](https://docs.n8n.io/integrations/creating-nodes/test/run-node-locally/).
+
+After restarting n8n, you should be able to search for "Example Node" to ensure that the nodes in this repo are being picked up properly.
+
+Development
+-----------
+Development means modifying the examples in `/nodes` and `/credentials`, and restarting the n8n server to pick up the changes (n8n doesn't have live reload).
+
+_NOTE: you can use `npm run lint` to check for linting errors, and `npm run lintfix` to try and automatically fix errors._
+
+### Devcontainer
+1. Make your changes
+1. Quit the terminal process in VSCode running the n8n server
+1. Run `start-n8n-with-custom-node.sh`
+1. Repeat
+
+### Your own environment
+1. Make your changes
+1. Quit the n8n process (however you started it)
+1. Restart it
+1. Repeat
+
+Publishing
+----------
+When you're ready to share your nodes with the community, do the following:
+
+1. Update the following fields in `package.json` to match your details:
+    - `name`
+    - `description`
+    - `version`
+    - `description`
+    - `repository`
+    - `homepage`
+    - `author.name`
+    - `author.email`
+1. Replace this README with documentation for your node. Use the [README_TEMPLATE](README_TEMPLATE.md) to get started.
+10. Update the [LICENSE](LICENSE.md) file to contain your own name at the top.
 11. [Publish](https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry) your package to npm.
 
-## More information
 
-Refer to our [documentation on creating nodes](https://docs.n8n.io/integrations/creating-nodes/) for detailed information on building your own nodes.
+License
-
+-------
-## License
 
 [MIT](https://github.com/n8n-io/n8n-nodes-starter/blob/master/LICENSE.md)

package.json

@@ -1,19 +1,19 @@
 {
-  "name": "n8n-nodes-<...>",
+  "name": "n8n-nodes-TODO-YOUR-NODE-HERE",
   "version": "0.1.0",
-  "description": "",
+  "description": "TODO YOUR DESCRIPTION HERE",
   "keywords": [
     "n8n-community-node-package"
   ],
   "license": "MIT",
-  "homepage": "",
+  "homepage": "TODO",
   "author": {
-    "name": "",
+    "name": "TODO",
-    "email": ""
+    "email": "TODO"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/<...>/n8n-nodes-<...>.git"
+    "url": "https://github.com/TODO/n8n-nodes-TODO.git"
   },
   "engines": {
     "node": ">=20.15"
@@ -25,7 +25,8 @@
     "format": "prettier nodes credentials --write",
     "lint": "eslint nodes credentials package.json",
     "lintfix": "eslint nodes credentials package.json --fix",
-    "prepublishOnly": "npm run build && npm run lint -c .eslintrc.prepublish.js nodes credentials package.json"
+    "prepublishOnly": "npm run build && npm run lint -c .eslintrc.prepublish.js nodes credentials package.json",
+    "getPackageName": "echo ${npm_package_name}"
   },
   "files": [
     "dist"

start-n8n-with-custom-node.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+set -e
+
+set -x
+
+N8N_NODES_DIR=~/.n8n/custom
+
+# Build the node
+npm install
+npm run lint
+npm run build
+npm link
+package_name="$(npm run getPackageName -s)"
+
+mkdir -p "${N8N_NODES_DIR}"
+cd "${N8N_NODES_DIR}"
+
+# Link the custom node into n8n
+npm link "${package_name}"
+
+# Start the server
+n8n