What Files Are Needed for an n8n Community Node?

If you're creating your first n8n community node, one of the first questions you'll probably have is:

“Okay, but what files do I actually need?”

When you open an existing n8n community node repository for the first time, it can look like a lot.

The good news is that you don't need to understand every file before you start.

Let's break it down.

The basic structure

A current n8n community node project can look roughly like this:

your-n8n-node/
├── .github/
├── credentials/
├── icons/
├── nodes/
├── package.json
├── package-lock.json
├── tsconfig.json
├── eslint.config.mjs
├── LICENSE.md
└── README.md

You may see additional files depending on the project, but these are the main pieces you'll commonly come across.

n8n provides a CLI that creates this structure for you:

npm create @n8n/node@latest n8n-nodes-example

There is also an official n8n node starter repository built on the same tooling. Either way, you don't have to create the project structure from an empty folder.

Now let's look at what each part actually does.

1. package.json

This is one of the most important files.

If you're familiar with npm, you probably already know what this is.

It contains information about your package, including things like:

• Package name
• Version
• Description
• Dependencies
• Build commands
• n8n configuration
• Package metadata

A simplified example might look like:

{
  "name": "n8n-nodes-example",
  "version": "1.0.0",
  "description": "n8n node for Example API",
  "keywords": ["n8n-community-node-package"],
  "license": "MIT",
  "author": { "name": "Your Name", "email": "you@example.com" },
  "repository": { "type": "git", "url": "https://github.com/you/n8n-nodes-example.git" },
  "scripts": {
    "build": "n8n-node build",
    "dev": "n8n-node dev",
    "lint": "n8n-node lint",
    "release": "n8n-node release"
  },
  "files": ["dist"],
  "n8n": {
    "n8nNodesApiVersion": 1,
    "credentials": ["dist/credentials/ExampleApi.credentials.js"],
    "nodes": ["dist/nodes/Example/Example.node.js"]
  },
  "devDependencies": { "@n8n/node-cli": "*" },
  "peerDependencies": { "n8n-workflow": "*" }
}

The parts n8n cares about most:

Field	Why it matters
name	Must start with n8n-nodes- (or @scope/n8n-nodes-)
keywords	n8n-community-node-package is how n8n finds community packages
n8n.nodes and n8n.credentials	Point to the compiled .js files in dist, not the .ts sources
repository and author	For verification, these must match the public GitHub repository
dependencies	Verified nodes can't have runtime dependencies, so keep this empty

The scaffold fills these in; check them before your first publish.

Think of package.json as the identity card for your node package.

It tells npm and n8n what your package is and how it should be handled.

2. The nodes/ directory

This is where your actual n8n node code lives.

For example:

nodes/
└── Example/
    ├── Example.node.ts
    └── Example.node.json

The .node.ts file is the node. The small .node.json "codex" file holds metadata such as the categories the node appears under and links to its documentation.

Inside the node file, you define things like:

• Node name
• Display name
• Description
• Inputs
• Resources
• Operations
• Parameters
• API requests
• Outputs

So if you're building a customer API integration, you might have:

Customer
 ├── Get
 ├── Get Many
 ├── Create
 ├── Update
 └── Delete

This is basically the part that turns your API into an actual n8n experience.

n8n supports both declarative and programmatic approaches for building nodes, depending on what your integration needs. n8n node building documentation

3. The credentials/ directory

If your API requires authentication, you'll probably have credential files too.

For example:

credentials/
└── ExampleApi.credentials.ts

This tells n8n how users should provide their credentials.

Maybe your API uses:

API Key
Bearer Token
Basic Auth
OAuth2

The credential configuration tells n8n how to collect that information and how it should be used when making API requests.

n8n has dedicated documentation for creating credentials for custom nodes. n8n credentials file reference. The NativeShip credentials guide compares the common setups

And this part matters because you don't want users manually entering authentication details for every operation.

They should configure their credentials once and use them throughout the node.

4. The icons/ directory

You may also have an icons/ directory:

icons/
├── example.svg
└── example.dark.svg

Reference them from the node description with icon: { light: 'file:../../icons/example.svg', dark: 'file:../../icons/example.dark.svg' }. Use SVG, and check that the icon is readable in both light and dark themes. n8n 3.0 removes the old defaults.color property, so the icon is now the only visual identity your node has in the editor.

This is where the node's icon assets can live.

It's not what makes your API integration work, but it helps your node look like a proper part of the n8n interface.

A custom node shouldn't just work.

It should also be easy for users to recognize.

5. tsconfig.json

Most n8n community nodes are written in TypeScript.

tsconfig.json tells TypeScript how your project should be compiled.

You generally don't need to spend much time changing this when starting out.

The n8n starter project already provides the basic configuration you need.

So think of it as:

“This tells TypeScript how to build my code.”

Not something you need to reinvent for every node.

6. package-lock.json

If you've used npm before, you've probably seen this file.

package-lock.json records the exact dependency versions used by your project.

For example, your package.json might say:

Use version 1.x of this dependency.

The lock file records the specific version that was installed.

This helps make builds more predictable.

You normally don't manually write this file.

npm creates and updates it for you.

7. README.md

This one isn't what makes your node work, but it's still important.

Your README is where you explain your node to other people.

For example:

# Example n8n Node

Connect n8n with Example API.

## Authentication

Add your Example API key.

## Operations

- Create Customer
- Get Customer
- Update Customer

If you're publishing a community node, don't treat the README as an afterthought.

Someone installing your node should be able to understand what it does and how to use it. The community node README checklist covers what to include.

LICENSE.md and eslint.config.mjs

The scaffold also adds a license file and a lint configuration. Keep the MIT license: n8n's verification rules require a public repository under MIT. The lint config runs n8n's own rules when you run npm run lint, which catches common problems such as missing descriptions or secret fields without password: true. Don't loosen these rules to make lint pass.

8. .github/

You may also see a .github directory:

.github/
└── workflows/

This is where GitHub-related automation can live.

For example, you can use GitHub Actions to:

• Run tests
• Build the node
• Check the project
• Publish a new version

This becomes especially useful when you want to automate your releases.

Instead of manually doing:

Build
↓
Test
↓
Publish

you can let a GitHub workflow handle those steps.

This is no longer optional. From May 1, 2026, n8n requires all community nodes to be published from a GitHub Action with npm provenance, so .github/workflows/publish.yml is a required file in practice. The npm provenance publishing guide walks through the setup, and what is trusted publishing explains why n8n asks for it.

What about the build output?

There's another important concept here.

You write your source code in TypeScript:

nodes/
└── Example/
    └── Example.node.ts

But your source code isn't necessarily what users install directly.

The project needs to be built into the appropriate output before it is published.

So you can think of the process like this:

TypeScript source
      ↓
     Build
      ↓
Package output
      ↓
     npm
      ↓
     n8n

The current n8n starter uses n8n's node tooling (n8n-node build) to handle the build and development workflow rather than requiring you to manually create an old-style gulpfile.js. The compiled files land in dist/, and only that folder is published. To try the node locally, run npm run dev; from n8n 3.0 this starts n8n in a container, so you need Docker or Podman installed.

That's worth mentioning because you may find older community-node tutorials that show files you don't need in a new project.

So what do you actually need?

If we strip everything down, the important pieces are roughly:

n8n community node
│
├── package.json
├── nodes/
│   └── YourNode.node.ts
├── credentials/
│   └── YourCredentials.credentials.ts
├── icons/
├── tsconfig.json
├── LICENSE.md
├── README.md
└── .github/workflows/publish.yml

Not every node needs exactly the same files.

For example, if your API doesn't need custom credentials, you may not need a credentials file.

If you don't have a custom icon, you may not need an icons/ directory either.

The exact structure depends on what your node does.

And this is where things get repetitive

The first time you create a community node, figuring this stuff out is actually useful.

You understand how n8n nodes work.

But imagine doing it again.

And again.

And again.

If you want to see these files assembled step by step, read how to turn an API into an n8n community node. Every new API means creating the project structure, setting up the files, adding credentials, defining operations, configuring the build, testing everything, preparing GitHub, and eventually publishing the package.

That's a lot of setup before you've even started thinking about the actual integration.

This is one of the things NativeShip is trying to simplify

This is basically the problem behind NativeShip.

You shouldn't have to start with:

“Which files do I need to create?”

every time you want to turn an API into an n8n node.

NativeShip takes the API you already have and helps generate the n8n node project around it.

That means the boring project setup is handled for you.

Instead of manually putting together:

package.json
nodes/
credentials/
icons/
build configuration
GitHub workflow
npm publishing

you can focus on the actual integration.

And because the project is yours, you still have the source code and the GitHub repository.

NativeShip is there to make the process easier, not hide your project from you.

One important thing

Don't copy files from a random n8n community node and assume everything will work.

Different nodes can have different requirements.

The safest place to understand the current structure and supported approaches is the official n8n documentation and starter repository. n8n creating nodes documentation

The structure and tooling can also change as n8n evolves.

So use existing nodes as examples, but use the official docs as your source of truth.

The simple way to think about it

You don't need a huge project to create an n8n community node.

At its core, you need:

Node code + package configuration + build setup.

Then you add things like credentials, icons, documentation, and GitHub automation depending on what your integration needs.

And if you're doing this once, learning the structure is worth it.

But if you're turning APIs into n8n nodes regularly, that's exactly where a tool like NativeShip can save you from repeating the same setup every time.

You bring the API.

NativeShip helps build the node around it.