DOCSEARCHbyAlgolia
Submit Docs

n8n Nodes Starter

repository·master·Indexed 22 days ago

https://github.com/n8n-io/n8n-nodes-starter

A starter repository for building, testing, and publishing custom n8n community nodes. It provides scaffolding via @n8n/node-cli, example imperative and declarative nodes, local development with hot reload, and automated publishing workflows to npm using GitHub Actions.

Tokens
2.4K
Snippets
10
Records
14
Agent score
78%

What's inside n8n-nodes-starter

  1. How declarative (low-code) nodes work

    master

    For integrations interacting with HTTP APIs, the declarative style is the recommended approach. Instead of writing manual request logic, you define operations, resources, and authentication declaratively. This significantly reduces boilerplate and allows n8n to handle requests automatically.

    Example patterns include:

    • Defining multiple resources (e.g., Issues, Comments).
    • Defining multiple operations (e.g., Get, Get All, Create).
    • Supporting multiple authentication methods (e.g., OAuth2 and Personal Access Token).
    • Implementing list search functionality for dynamic dropdowns.

  2. Develop n8n nodes locally with hot reload

    master

    To start developing with your nodes loaded and hot reload enabled, use the dev script. This runs n8n-node dev, which builds your node in watch mode, starts n8n with your node available, and automatically opens n8n in your browser (typically at http://localhost:5678).

    npm run dev

  3. Structure a README for an n8n community node

    master

    When creating a new n8n community node, use the provided template to ensure users have all necessary information. A standard community node README should include the following sections:

    • Description: Clearly state what the node does and which service it integrates with.
    • Installation: Direct users to the official n8n community nodes installation guide.
    • Operations: List all supported actions/operations the node can perform.
    • Credentials: (If applicable) Detail authentication requirements, prerequisites (like signing up for a service), and setup steps.
    • Compatibility: Specify the minimum n8n version required and any known version issues.
    • Usage: Provide guidance for complex or non-obvious workflows.
    • Resources: Link to the service's official documentation and n8n community node docs.
    • Version history: (If applicable) Document changes and compatibility impacts across versions.

  5. Release and publish to npm

    master

    The starter includes a GitHub Actions workflow (.github/workflows/publish.yml) that handles publishing to npm on every version tag push. This workflow uses OIDC for provenance attestation.

    Releasing a new version

    Run the release script to automate the versioning process. This script lints, builds, prompts for a version bump, updates the changelog, commits, tags, and pushes the changes:

    npm run release

    One-time GitHub Actions setup

    To allow GitHub Actions to publish on your behalf without storing secrets, configure Trusted Publishers in your npmjs.com package settings:

    • Repository owner: your GitHub username or org
    • Repository name: your repo name
    • Workflow name: publish.yml

  6. Build and Lint n8n nodes

    master

    Use the following commands to maintain code quality and prepare for production:

    • Linting: Check for errors and style issues with npm run lint. Use npm run lint:fix to automatically fix common issues.
    • Production Build: Compile TypeScript code to the dist/ folder using npm run build.
    npm run lint
npm run lint:fix
npm run build

  7. Configure your n8n node package

    master

    When setting up your repository, ensure your package.json is correctly configured:

    1. Package Name: The name field must start with n8n-nodes-.
    2. Node Registration: Your node must be registered in the n8n.nodes array within package.json so n8n can discover it.
    3. Metadata: Update author, repository, and description to reflect your project.

  8. Troubleshoot missing nodes in n8n

    master

    If your node does not appear in the n8n interface, check the following:

    1. Dependencies: Ensure you have run npm install.
    2. Registration: Verify the node is listed in package.json under the n8n.nodes key.
    3. Server State: Restart the development server using npm run dev.
    4. Logs: Check the terminal console for any error messages during the build or startup process.

  9. Configure ESLint using @n8n/node-cli

    master

    This project uses a centralized ESLint configuration provided by the @n8n/node-cli/eslint package. To maintain consistency with n8n node development standards, you should export the config object from your eslint.config.mjs file rather than defining custom rules manually.

    import { config } from '@n8n/node-cli/eslint';

export default config;

  10. Available npm scripts for n8n node development

    master

    The following scripts are provided via the @n8n/node-cli to streamline the development lifecycle:

    | Script | Description |
| :--- | :--- |
| `npm run dev` | Start n8n with your node and watch for changes (runs `n8n-node dev`) |
| `npm run build` | Compile TypeScript to JavaScript for production (runs `n8n-node build`) |
| `npm run build:watch` | Build in watch mode (auto-rebuild on changes) |
| `npm run lint` | Check your code for errors and style issues (runs `n8n-node lint`) |
| `npm run lint:fix` | Automatically fix linting issues when possible (runs `n8n-node lint --fix`) |
| `npm run release` | Create a new release (runs `n8n-node release`) |

  11. Configure GitHub Issue Comment operations

    master

    When using the GitHub node with the issueComment resource, you can perform the Get Many operation to retrieve issue comments. This operation requires the repository owner and the repository name to construct the request URL.

    Operation Details:

    • Operation Name: Get Many (getAll)
    • Action: Get issue comments
    • HTTP Method: GET
    • Endpoint Pattern: /repos/{{$parameter.owner}}/{{$parameter.repository}}/issues/comments

    Note that the owner and repository parameters are required for this operation to function correctly.

    {
  "resource": "issueComment",
  "operation": "getAll",
  "owner": "owner_name",
  "repository": "repo_name"
}

  12. Define GitHub Issue resource properties with issueDescription

    master

    The issueDescription constant defines the configuration for the 'issue' resource within a GitHub node. It is an array of INodeProperties that handles the selection of operations and the subsequent parameters required for those operations.

    When the resource is set to issue, the following operations are available:

    • Get Many (getAll): Fetches multiple issues from a repository. Uses GET on /repos/{{$parameter.owner}}/{{$parameter.repository}}/issues.
    • Get (get): Fetches data for a single specific issue. Uses GET on /repos/{{$parameter.owner}}/{{$parameter.repository}}/issues/{{$parameter.issue}}.
    • Create (create): Creates a new issue. Uses POST on /repos/{{$parameter.owner}}/{{$parameter.repository}}/issues.

    The description automatically includes repository owner and name selectors (repoOwnerSelect and repoNameSelect) and spreads additional property descriptions based on the selected operation (issueGetManyDescription, issueGetDescription, and issueCreateDescription).

    import { issueDescription } from './nodes/GithubIssues/resources/issue/index';

// issueDescription is used within the main node definition to provide
// the UI fields for the 'issue' resource.
export const nodeProperties: INodeProperties[] = [
    // ... other resource definitions
    ...issueDescription,
];