Imported from shotium/n8n-nodes-shotium (AGENTS.md). Install upstream with npx skills add shotium/n8n-nodes-shotium. Copyright stays with the author.

n8n community node

Overview

This is a project containing code for an n8n community node. n8n is a workflow automation platform where users build workflows with nodes, which are the building block of a workflow. Nodes can perform a range of actions, such as starting a workflow (called a "trigger node"), fetching and sending data, or processing and manipulating it. Besides that there are credentials - entities that store sensitive information on how to connect to external services and APIs. A node can require some credentials to be used. Community nodes are a way for anyone to create such nodes and add them to be used in n8n. All community nodes are named in a format: n8n-nodes-<n> or @org/n8n-nodes-<n>. Community nodes can also be submitted for approval to be used on n8n Cloud version. In that case there are rules that the node needs to follow in order to be approved

Important notes

• Follow the rules and guidelines in this document and the linked docs below over any code examples.
• All code blocks in these docs are illustrative and incomplete. They MUST NOT be copied verbatim or assumed to be the final desired code.
• Replace example names like Example, Wordpress, wordpressApi, etc. with names that match the actual service / node you are building.
• When in doubt, generalize from the patterns, don't replicate the exact structure, fields, or values from the examples.
• Produce the full implementation needed for the current project (nodes, credentials, tests, etc.), not just fragments similar to examples.
• If an example omits parts (e.g. types, operations, properties), infer and implement the missing parts based on the real requirements / API docs.
• Never output Wordpress-specific code unless the project is actually about WordPress.

Project structure

There are two main folders in this project:

• nodes contains all of the nodes in a package (there can be more than 1). The code for each node usually lives in its own folder
• credentials contains all of the credentials in a package. Usually it's just a single file for every credential So it looks something like this: . ├── nodes/ │ └── Example/ │ ├── Example.node.ts │ └── ... ├── credentials/ │ └── Example.credentials.ts ├── package.json └── ... It's important to note that package.json has a special field n8n that have information about nodes and credentials in a package:

{
  "name": "n8n-nodes-example",
  "version": "1.0.0",
  "n8n": {
    "n8nNodesApiVersion": 1,
    "strict": true,
    "credentials": [
        "dist/credentials/Example.credentials.js"
    ],
    "nodes": [
      "dist/nodes/Example/Example.node.js"
    ]
  }
}

nodes and credentials keys contain paths to transpiled JS files in a dist folder for the nodes and credentials respectively. If you add/remove/rename nodes and/or credentials, you need to make sure to update n8n.nodes and n8n.credentials keys in package.json accordingly. Initial files in the project may contain example nodes and/or credentials that need to be removed or renamed once you start making an actual node.

Key guidelines

• Use the n8n-node CLI tool whenever possible for building, dev mode, linting, etc.
• Always address any lint/typecheck errors/warnings, unless there is a very specific reason to ignore/disable it
• Make sure to use proper types whenever possible
• If you are updating the npm package version, make sure to update CHANGELOG.md in the root of the repository
• Read .agents/workflow.md for more info

Release checklist

Publishing is automated: pushing a version tag (*.*.*, no v prefix) triggers .github/workflows/publish.yml, which publishes to npm with provenance. Never run npm run release locally. Follow these steps in order — everything must be committed before the tag is pushed, otherwise the npm tarball ships stale files:

1. Run npm version <version> --no-git-tag-version to update package.json and package-lock.json together
2. Add the new version entry to CHANGELOG.md
3. Add the new version entry to README.md → ## Version history
4. npm run lint && npm run build pass locally
5. Confirm package.json, package-lock.json, CHANGELOG.md, and README.md all contain the exact release version
6. Commit and git push origin main
7. Confirm main CI is green for the release commit before tagging: GH_PAGER=cat gh run list --workflow ci.yml --branch main --limit 1
8. git tag <version> && git push origin <version> — this triggers the npm publish
9. Verify that tag's Publish run succeeded: GH_PAGER=cat gh run list --workflow publish.yml --branch <version> --limit 1
10. Verify npm published that exact version: npm view n8n-nodes-shotium@<version> version
11. Create the GitHub release (body = the CHANGELOG entry for this version): gh release create <version> --title <version> --notes '<changelog bullets>'
12. Verify the GitHub release exists: GH_PAGER=cat gh release view <version>
13. If this release addresses n8n verification feedback, reply to the review thread

Verification status

• Approved 2026-09-04, live on n8n Cloud the same day (n8n's "published on n8n cloud" email). Cloud users find the node in the nodes panel; they may need to enable Verified Community Nodes in the admin panel.
• Integrations page (2-4 weeks after approval) — n8n builds a dedicated page for the node on n8n.io, populated from the Node Details form in the Creator Portal. Keep that form current; it is the only copy we control there.
• Updates: n8n monitors npm and picks up new versions after a quick re-review. Every change must be visible in this GitHub repository or n8n cannot verify the version update. First exercised with 0.1.4: re-review passed and the version was live on Cloud by 2026-09-06, so the path is confirmed to work without any manual resubmission.
• 0.1.4 (re-review passed, live 2026-09-06) closed the post-verification queue: main-repo copy (blog post, /integrations/n8n, .agents/product-marketing.md, changelog) now says "verified", README covers Cloud install and Google sign-in, codex adds Marketing & Content and links https://shotium.com/integrations/n8n. The developer-experience feedback n8n asked for (codex node identifier lint, silent category drops, partial Node Details carry-over) was sent to the review thread. The "open graph" action string stays lowercase on purpose: the n8n lint rule node-param-operation-option-action-miscased enforces sentence case.
• Integrations page live (https://n8n.io/integrations/shotium/, arrived 2026-09-12, ahead of the 2-4 week estimate): content matches the Creator Portal submission — Long Form Description, Development/Utility/Marketing categories, logo, GitHub link. No portal fix needed. This closes the post-verification queue; nothing further is expected from n8n unless a new version needs re-review.

Context-specific docs

Load these before working on the relevant area:

Additional resources

If you need any extra information, here are links to n8n's official docs regarding building community nodes:

• https://docs.n8n.io/integrations/community-nodes/build-community-nodes/
• https://docs.n8n.io/integrations/creating-nodes/overview/
• https://docs.n8n.io/integrations/creating-nodes/build/reference/
• https://docs.n8n.io/integrations/creating-nodes/build/reference/ux-guidelines/