@n8n/create-node

A powerful scaffolding tool to quickly create custom n8n community nodes with best practices built-in.

🚀 Quick Start

Create a new n8n node in seconds:

npm create @n8n/node@latest # or pnpm/yarn/...

Follow the interactive prompts to configure your node, or specify options directly:

npm create @n8n/node my-awesome-node --template declarative/custom

📋 Command Line Options

npm create @n8n/node [NAME] [OPTIONS]

Options

| Flag | Description | |------|-------------| | -f, --force | Overwrite destination folder if it already exists | | --skip-install | Skip automatic dependency installation | | --template <template> | Specify which template to use |

Available Templates

• declarative/custom - Start with a minimal declarative node structure
• declarative/github-issues - GitHub Issues integration example
• programmatic/example - Full programmatic node with advanced features

🎯 Interactive Setup

The CLI will guide you through setting up your node:

$ npm create @n8n/node
┌ @n8n/create-node
│
◇ What is your node called?
│ my-awesome-api-node
│
◇ What kind of node are you building?
│ HTTP API
│
◇ What template do you want to use?
│ Start from scratch
│
◇ What's the base URL of the API?
│ https://api.example.com/v1
│
◇ What type of authentication does your API use?
│ API Key
│
◇ Files copied ✓
│
◇ Dependencies installed ✓
│
◇ Next Steps ─────────────────────────────────────────────────────────────────────╮
│                                                                                  │
│  cd ./my-awesome-api-node && npm run dev                                       │
│                                                                                  │
│  📚 Documentation: https://docs.n8n.io/integrations/creating-nodes/            │
│  💬 Community: https://community.n8n.io                                        │
│                                                                                  │
├──────────────────────────────────────────────────────────────────────────────────╯
│
└ Created ./my-awesome-api-node ✨

🛠️ Development Workflow

1. Navigate to your project

cd ./my-awesome-api-node

2. Start development server

npm run dev

This command:

• Starts n8n in development mode on http://localhost:5678
• Enables hot reload for your node changes
• Automatically includes your node in the n8n instance
• Links your node to ~/.n8n-node-cli/.n8n/custom for development
• Watches for file changes and rebuilds automatically

3. Test your node

• Open n8n at http://localhost:5678
• Create a new workflow
• Find your node in the node panel
• Test parameters and functionality in real-time

📦 Generated Project Commands

Your generated project comes with these convenient npm scripts:

Development

npm run dev
# Runs: n8n-node dev

Building

npm run build
# Runs: n8n-node build

Linting

npm run lint
# Runs: n8n-node lint

npm run lint:fix
# Runs: n8n-node lint --fix

Publishing

npm run release
# Runs: n8n-node release

📦 Build & Deploy

Build for production

npm run build

Generates:

• Compiled TypeScript code
• Bundled node package
• Optimized assets and icons
• Ready-to-publish package

Quality checks

npm run lint

Validates:

• Code style and formatting
• n8n node conventions
• Common integration issues
• Cloud publication readiness

Cloud support

npx n8n-node cloud-support

Manage n8n Cloud publication eligibility. In strict mode, your node must use the default ESLint config and pass all community node rules to be eligible for n8n Cloud publication.

Fix issues automatically:

npm run lint:fix

Publish your node

npm run release

Runs release-it to handle the complete release process:

• Ensures working directory is clean
• Verifies you're on the main git branch
• Increments your package version
• Runs build and lint checks
• Updates changelog
• Creates git tag with version bump
• Creates GitHub release with changelog
• Publishes to npm

📁 Project Structure

Your generated project includes:

my-awesome-api-node/
├── src/
│   ├── nodes/
│   │   └── MyAwesomeApi/
│   │       ├── MyAwesomeApi.node.ts    # Main node logic
│   │       └── MyAwesomeApi.node.json  # Node metadata
│   └── credentials/
│       └── MyAwesomeApiAuth.credentials.ts
├── package.json
├── tsconfig.json
└── README.md

The CLI expects your project to follow this structure for proper building and development.

⚙️ Configuration

The CLI reads configuration from your package.json:

{
  "name": "n8n-nodes-my-awesome-node",
  "n8n": {
    "n8nNodesApiVersion": 1,
    "nodes": [
      "dist/nodes/MyAwesomeApi/MyAwesomeApi.node.js"
    ],
    "credentials": [
      "dist/credentials/MyAwesomeApiAuth.credentials.js"
    ]
  }
}

🎨 Node Types

Choose the right template for your use case:

| Template | Best For | Features | |----------|----------|----------| | Declarative | REST APIs, simple integrations | JSON-based configuration, automatic UI generation | | Programmatic | Complex logic, custom operations | Full TypeScript control, advanced error handling |

🐛 Troubleshooting

Common Issues

Node not appearing in n8n:

# Clear n8n node cli cache and restart
rm -rf ~/.n8n-node-cli/.n8n/custom
npm run dev

TypeScript errors:

# Reinstall dependencies
rm -rf node_modules npm-lock.yaml
npm install

Build failures:

# Check for linting issues first
npm run lint --fix
npm run build

Development server issues:

# Clear cache and restart development server
rm -rf ~/.n8n-node-cli/.n8n/custom
npm run dev

🔧 Advanced Usage

Using External n8n Instance

If you prefer to use your own n8n installation:

npm run dev --external-n8n

Custom User Folder

Specify a custom location for n8n user data:

npm run dev --custom-user-folder /path/to/custom/folder

📚 Resources

• Node Development Guide - Complete documentation
• API Reference - Technical specifications
• Community Forum - Get help and share your nodes
• Node Examples - Official node implementations
• @n8n/node-cli - The underlying CLI tool

🤝 Contributing

Found a bug or want to contribute? Check out the n8n repository and join our community!

Happy node building! 🎉