What Should an n8n Community Node README Contain?

An n8n community node README should let someone answer four questions before trusting the package: Can I install it on my n8n setup? What access does it need? Which operation can I run first? Where do I go when that operation fails? Write those answers for the exact version on npm, then check them against the node UI and an actual workflow.

n8n asks verification candidates for appropriate documentation in the npm package README or a related public repository. That requirement is broad. A useful README goes further than naming the files in a package, which the NativeShip package-files article already covers. It gives a user a route from installation to a first result, and gives a maintainer enough detail to reproduce a report.

First, make the README match the release

The public TidyCal node README lists operations and a generic example workflow. It also says the integration requires no credentials. I checked the current npm registry version, @nativeship/n8n-nodes-tidycal@1.0.1, on 20 October 2026. Its packaged README repeats that claim, and the compiled node declares no n8n credential. TidyCal's API documentation says API access requires a paid plan and requests need an access token or OAuth authorization.

That mismatch is already enough to stop recommending the README as a setup guide. A reader cannot fix it by following more detailed prose if the shipped node has no matching credential field. The package needs a corrected authentication path and an authenticated test first. The README should then describe the new version's real setup, not a hoped-for setup for 1.0.1.

The same check applies to every release: read the npm README, inspect the package metadata and node fields, and try the instructions against the published package. A repository change on its own does not update the README displayed for an older npm version. npm's README guidance says the package page updates when a new version is published.

Give the reader a useful first screen

Open with the exact package name, the service it connects to, and one sentence about the job it handles. Say whether the package contains actions, triggers, or both. Link to the source repository and issue tracker, and identify who maintains it. If you have tested a particular n8n version or deployment type, name it; if you have not, avoid a blanket compatibility claim.

Then put the practical requirements close to the top. For TidyCal, a real requirement is paid-plan API access. For another service it may be an OAuth app, an administrator role, or a permitted API scope. Keep product account requirements separate from n8n installation requirements so a user can see which system blocks them.

README section	What the reader needs	What to verify before writing it
Install and compatibility	Exact npm package name; supported n8n environments and versions actually checked	Current n8n installation path and a real install of this release
Credentials	Where to obtain access, credential type, required permissions, and a safe connection check	Service docs and the credential fields in the shipped node
Operations	Resource and action names as displayed in n8n, plus any trigger events	Node UI and the behavior of the matching package
First workflow	A small example with setup, input, expected output shape, and one common failure	A redacted execution or a clearly marked untested example
Limits and support	Known gaps, rate limits where relevant, support route, repository, license, and release history	API limits, package metadata, and a working contact or issue path

This is an editorial checklist, not a claim that n8n requires these exact headings. n8n's submission documentation requires appropriate documentation and separately checks technical and UX criteria. A complete README does not itself grant verification. Readers who check a community node before installing it will compare your README with the package, so the two should agree.

Show the installation path you have checked

Use the exact npm package name. Explain where a user can install it in the n8n environment you tested, and link to n8n's current installation instructions for environments you have not tested. Keep development commands such as npm run dev in a maintainer section; they are not instructions for a customer who wants to add a released package to an existing workflow.

Do not describe a package as available through n8n's in-editor verified-node discovery merely because it appears on npm. Publication and n8n verification are separate stages. The NativeShip publishing guide explains the release path; the submission guide covers the later Creator Portal task.

If the installation method depends on self-hosting, administrator settings, or a specific n8n plan, state the checked condition and date. This matters more from n8n 3.0, which sets N8N_UNVERIFIED_PACKAGES_ENABLED=false by default: an unverified package will not install on a self-hosted instance until an admin enables that setting, and n8n Cloud only offers verified nodes. Say which case applies to your package, and update the README when n8n verification is approved. Link to the current official method rather than copying a command from a different package. An exact install command is useful only when it works in the stated environment.

Explain credentials without exposing them

A good credential section tells the user where to create the access token or OAuth client, which scopes or account permissions are needed, which n8n credential fields receive those values, and how to check the connection. It should never paste a real secret into a screenshot, example workflow, or issue report.

For the TidyCal package, a truthful current note would say that version 1.0.1 has an unresolved authentication mismatch and should not be presented as a working authenticated integration. Once a corrected version has a credential field and a successful test, its README can give the exact setup steps. The NativeShip credentials guide explains how n8n node credentials are structured; the package README still has to name the fields and permissions that this particular node uses.

If a credential test succeeds but an operation fails, the README should help the reader separate an invalid token from a missing permission, wrong account, wrong resource ID, or invalid request. Do not promise that a green credential check proves every operation works. If your node has one, adding a credential test explains how it works and what it can and cannot catch.

Walk through one real operation

“Add the node, select an operation, and execute” leaves the important choices to the user. Pick one low-risk operation and document it at the level a first-time user needs:

1. State the prerequisite, including a test account and any required record or resource ID.
2. Name the resource and operation exactly as they appear in n8n.
3. Show the required fields with safe example values and explain any date or timezone format.
4. Show the expected output fields from a redacted run, or mark the example untested until that run exists.
5. Add one short failure case and the first thing to check.

For TidyCal, “List Booking Types” could be a sensible first read after authentication is fixed. That is a proposed example, not a result from version 1.0.1. The current README's Manual Trigger -> TidyCal -> destination node sketch does not tell a reader which resource to select, what access to provide, or what output to expect.

An exported workflow can help, but remove credentials, personal data, internal URLs, and account-specific IDs before sharing it. Make sure it imports and runs with the released package version. A diagram cannot substitute for those checks.

Tell users what is missing and where to report it

List meaningful gaps next to the supported operations: unsupported API methods, missing triggers, pagination behavior, service plan restrictions, and any operation that has not been tested. Avoid a broad “supports TidyCal” claim if only some actions have evidence.

Give users one support route that is monitored, plus the details that make a report actionable: n8n version, package version, resource and operation, redacted input, error text, and whether the same request works directly against the API. Name a release history or changelog so users can tell whether a fix applies to their version. State the license and link the repository if the package is public.

A README skeleton you can copy

Write the README in English, since n8n's verification rules require English-only package content. Replace the bracketed parts:

# n8n-nodes-[service]

An n8n community node for [Service]. It lets you [main job] in your n8n workflows.

Contains: [actions / trigger / both]. Maintained by [name or company] ([support link]).

## Installation
[Verified: install from the nodes panel in n8n. / Not yet verified: self-hosted only; an admin must set N8N_UNVERIFIED_PACKAGES_ENABLED=true on n8n 3.0+, then install `n8n-nodes-[service]` from Settings > Community Nodes.]
Tested with n8n [version] on [Cloud / self-hosted Docker].

## Credentials
1. In [Service], go to [path] and create [token type] with [scopes].
2. In n8n, create a "[Service] API" credential and paste the token.
3. Save. n8n checks the connection with [endpoint].

## Operations
| Resource | Operation | Notes |
| --- | --- | --- |
| [Resource] | [Operation] | [limits, required IDs] |

## First workflow
Manual Trigger -> [Service]: [Resource] > [Operation] with [example input].
Expected output: [fields]. If you see [error], check [first fix].

## Limits
[Rate limits, plan restrictions, unsupported endpoints.]

## Version history
- [version] ([date]): [user-visible change and any migration step]

## License
MIT

Before shipping a README update, follow its first workflow yourself on the npm version the reader will install. If a step fails, fix the package or the instruction, publish a new version where necessary, and run that workflow again.