@n8n/node-cli 0.3.0 → 0.5.0

package/README.md

@@ -1,47 +1,272 @@
 # @n8n/node-cli
 
-Official CLI for developing community nodes for [n8n](https://n8n.io).
+Official CLI for developing community nodes for n8n.
 
-## Features
+## 🚀 Getting Started
 
-- 🔧 Scaffold new n8n nodes
-- 💻 Develop n8n nodes with live preview
+**To create a new node**, run:
 
-## Installation
+```bash
+pnpm create @n8n/node
+```
+
+This will generate a project with `pnpm` scripts that use this CLI under the hood.
+
+## 📦 Generated Project Commands
+
+After creating your node with `pnpm create @n8n/node`, you'll use these commands in your project:
+
+### Development
+```bash
+pnpm dev
+# Runs: n8n-node dev
+```
+
+### Building
+```bash
+pnpm build
+# Runs: n8n-node build
+```
+
+### Linting
+```bash
+pnpm lint
+# Runs: n8n-node lint
+
+pnpm lint:fix
+# Runs: n8n-node lint --fix
+```
+
+### Publishing
+```bash
+pnpm run release
+# Runs: n8n-node release
+```
+
+## 🛠️ CLI Reference
+
+> **Note:** These commands are typically wrapped by `pnpm` scripts in generated projects.
 
-Run directly via `npx`:
+```bash
+n8n-node [COMMAND] [OPTIONS]
+```
+
+### Commands
+
+#### `n8n-node new`
+
+Create a new node project.
 
 ```bash
-npx n8n-node new
+n8n-node new [NAME] [OPTIONS]
 ```
 
-Or install globally:
+**Flags:**
+| Flag | Description |
+|------|-------------|
+| `-f, --force` | Overwrite destination folder if it already exists |
+| `--skip-install` | Skip installing dependencies |
+| `--template <template>` | Choose template: `declarative/custom`, `declarative/github-issues`, `programmatic/example` |
 
+**Examples:**
 ```bash
-npm install -g @n8n/node-cli
 n8n-node new
+n8n-node new n8n-nodes-my-app --skip-install
+n8n-node new n8n-nodes-my-app --force
+n8n-node new n8n-nodes-my-app --template declarative/custom
+```
+
+> **Note:** This command is used internally by `pnpm create @n8n/node` to provide the interactive scaffolding experience.
+
+#### `n8n-node dev`
+
+Run n8n with your node in development mode with hot reload.
+
+```bash
+n8n-node dev [--external-n8n] [--custom-user-folder <value>]
 ```
 
-## Commands
+**Flags:**
+| Flag | Description |
+|------|-------------|
+| `--external-n8n` | Run n8n externally instead of in a subprocess |
+| `--custom-user-folder <path>` | Folder to use to store user-specific n8n data (default: `~/.n8n-node-cli`) |
 
-## Create a node
+This command:
+- Starts n8n on `http://localhost:5678` (unless using `--external-n8n`)
+- Links your node to n8n's custom nodes directory (`~/.n8n-node-cli/.n8n/custom`)
+- Rebuilds on file changes for live preview
+- Watches for changes in your `src/` directory
 
+**Examples:**
 ```bash
-n8n-node new   # Scaffold a new node
+# Standard development with built-in n8n
+n8n-node dev
+
+# Use external n8n instance
+n8n-node dev --external-n8n
+
+# Custom n8n extensions directory
+n8n-node dev --custom-user-folder /home/user
 ```
 
-## Build a node
+#### `n8n-node build`
+
+Compile your node and prepare it for distribution.
 
 ```bash
-n8n-node build   # Build your node; should be ran in the root of your custom node
+n8n-node build
 ```
 
-## Develop a node
+**Flags:** None
+
+Generates:
+- Compiled TypeScript code
+- Bundled node package
+- Optimized assets and icons
+- Ready-to-publish package in `dist/`
+
+#### `n8n-node lint`
+
+Lint the node in the current directory.
 
 ```bash
-n8n-node dev  # Develop your node with hot reloading; should be ran in the root of your custom node
+n8n-node lint [--fix]
 ```
 
-## Related
+**Flags:**
+| Flag | Description |
+|------|-------------|
+| `--fix` | Automatically fix problems |
+
+**Examples:**
+```bash
+# Check for linting issues
+n8n-node lint
+
+# Automatically fix fixable issues
+n8n-node lint --fix
+```
+
+#### `n8n-node release`
+
+Publish your community node package to npm.
+
+```bash
+n8n-node release
+```
+
+**Flags:** None
+
+This command handles the complete release process using [release-it](https://github.com/release-it/release-it):
+- Builds the node
+- Runs linting checks
+- Updates changelog
+- Creates git tags
+- Creates GitHub releases
+- Publishes to npm
+
+## 🔄 Development Workflow
+
+The recommended workflow using the scaffolding tool:
+
+1. **Create your node**:
+   ```bash
+   pnpm create @n8n/node my-awesome-node
+   cd my-awesome-node
+   ```
+
+2. **Start development**:
+   ```bash
+   pnpm dev
+   ```
+   - Starts n8n on `http://localhost:5678`
+   - Links your node automatically
+   - Rebuilds on file changes
+
+3. **Test your node** at `http://localhost:5678`
+
+4. **Lint your code**:
+   ```bash
+   pnpm lint
+   ```
+
+5. **Build for production**:
+   ```bash
+   pnpm build
+   ```
+
+6. **Publish**:
+   ```bash
+   pnpm run release
+   ```
+
+## 📁 Project Structure
+
+The CLI expects your project to follow this structure:
+
+```
+my-node/
+├── src/
+│   ├── nodes/
+│   │   └── MyNode/
+│   │       ├── MyNode.node.ts
+│   │       └── MyNode.node.json
+│   └── credentials/
+├── package.json
+└── tsconfig.json
+```
+
+## ⚙️ Configuration
+
+The CLI reads configuration from your `package.json`:
+
+```json
+{
+  "name": "n8n-nodes-my-awesome-node",
+  "n8n": {
+    "n8nNodesApiVersion": 1,
+    "nodes": [
+      "dist/nodes/MyNode/MyNode.node.js"
+    ],
+    "credentials": [
+      "dist/credentials/MyNodeAuth.credentials.js"
+    ]
+  }
+}
+```
+
+## 🐛 Troubleshooting
+
+### Development server issues
+```bash
+# Clear n8n custom nodes cache
+rm -rf ~/.n8n-node-cli/.n8n/custom
+
+# Restart development server
+pnpm dev
+```
+
+### Build failures
+```bash
+# Run linting first
+pnpm lint
+
+# Clean build
+pnpm build
+```
+
+## 📚 Resources
+
+- **[Creating Nodes Guide](https://docs.n8n.io/integrations/creating-nodes/)** - Complete documentation
+- **[Node Development Reference](https://docs.n8n.io/integrations/creating-nodes/build/reference/)** - API specifications
+- **[Community Forum](https://community.n8n.io)** - Get help and showcase your nodes
+- **[@n8n/create-node](https://www.npmjs.com/package/@n8n/create-node)** - Recommended scaffolding tool
+
+## 🤝 Contributing
+
+Found an issue? Contribute to the [n8n repository](https://github.com/n8n-io/n8n) on GitHub.
+
+---
 
-`@n8n/create-node`: Lightweight wrapper to support `npm create @n8n/node`
+**Happy node development! 🎉**