n8n-workflow-manager

Command-line tools for managing n8n workflows with version control and TypeScript support

🚀 Quick Start

Installation

npm install --save-dev n8n-workflow-manager

Initialize your project

npx n8n-workflow-manager init

Basic Usage

# Split n8n workflows into individual files
npx n8n-workflow-manager split

# Package files back into n8n workflow JSON
npx n8n-workflow-manager package

# Generate TypeScript types
npx n8n-workflow-manager types

📖 What is n8n-workflow-manager?

Example: Splitting an n8n workflow into organized files

n8n-workflow-manager is a powerful CLI tool that helps you manage n8n workflows with proper version control, TypeScript support, and team collaboration features. It solves the common problems of:

• Version Control: n8n workflows are large JSON files that are difficult to version control and review
• Team Collaboration: Multiple developers can't easily work on the same workflow
• Code Organization: Complex workflows become hard to maintain and understand
• Type Safety: No TypeScript support for workflow development

🎯 Features

✨ Core Features

• 🔄 Bidirectional Conversion: JSON ↔ Individual Files
• 📁 Smart File Organization: Automatic directory structure creation
• 🎯 Interactive Workflow Selection: Choose which workflows to process
• 🔧 Configurable: Customize behavior via n8n-config.json
• 📦 Local Installation: No global dependencies required

🔧 Advanced Features

• 🏷️ TypeScript Support: Generate type definitions for workflows
• 💾 Backup Creation: Automatic backups before packaging
• ✅ Workflow Validation: Validate workflow structure and integrity
• 📊 Progress Reporting: Detailed operation statistics
• 🔍 Code Node Extraction: Split JavaScript/TypeScript code into separate files

📋 Commands

npx n8n-workflow-manager init

Initialize n8n workflow management in your project.

npx n8n-workflow-manager init

Options:

• --force - Overwrite existing configuration

npx n8n-workflow-manager split

Extract n8n workflows into individual files for version control.

# Interactive selection
npx n8n-workflow-manager split

# Split all workflows
npx n8n-workflow-manager split --all

# Split specific workflow
npx n8n-workflow-manager split --workflow bug-tracker

Options:

• --workflow <name> - Split specific workflow
• --all - Split all workflows
• --dry-run - Preview changes without making them

npx n8n-workflow-manager package

Package individual files back into n8n workflow JSON.

# Interactive selection
npx n8n-workflow-manager package

# Package all workflows
npx n8n-workflow-manager package --all

# Package specific workflow
npx n8n-workflow-manager package --workflow bug-tracker

Options:

• --workflow <name> - Package specific workflow
• --all - Package all workflows
• --dry-run - Preview changes without making them

npx n8n-workflow-manager types

Generate TypeScript type definitions for workflows.

# Generate types for all workflows
npx n8n-workflow-manager types

# Generate types for specific workflow
npx n8n-workflow-manager types --workflow bug-tracker

Options:

• --workflow <name> - Generate types for specific workflow
• --all - Generate types for all workflows
• --base - Generate base type definitions only

⚙️ Configuration

Create n8n-config.json in your project root to customize behavior:

{
  "workflowsDir": "workflows",
  "n8nDir": "n8n",
  "generateTypes": true,
  "typeScript": {
    "enabled": true,
    "outputDir": "types"
  },
  "ignore": [
    "node_modules",
    ".git",
    ".env",
    ".env.*"
  ],
  "extraction": {
    "preserveIds": true,
    "generateIndex": true,
    "splitCodeNodes": true
  },
  "packaging": {
    "validateWorkflows": true,
    "minifyOutput": false,
    "backupOriginal": true
  }
}

Configuration Options

Option	Description	Default
workflowsDir	Directory for extracted workflows	workflows
n8nDir	Directory for n8n JSON files	n8n
generateTypes	Generate TypeScript types	true
typeScript.enabled	Enable TypeScript support	true
typeScript.outputDir	TypeScript output directory	types
extraction.preserveIds	Keep original node IDs	true
extraction.generateIndex	Generate node index files	true
extraction.splitCodeNodes	Split code nodes into separate files	true
packaging.validateWorkflows	Validate workflow structure	true
packaging.backupOriginal	Backup before packaging	true

📁 Directory Structure

Example: Edit workflow code directly in your IDE with syntax highlighting

After initialization, your project will have:

your-project/
├── n8n/                     # n8n workflow JSON files
│   ├── bug-tracker.json     # Original workflow exports
│   └── github-pr.json
├── workflows/               # Extracted workflow files
│   ├── bug-tracker/
│   │   ├── workflow.json    # Base workflow structure
│   │   ├── metadata.json    # Workflow metadata
│   │   ├── connections.json # Node connections
│   │   ├── nodes/          # Individual node files
│   │   │   ├── webhook.json
│   │   │   ├── code-node.js
│   │   │   └── linear-create.json
│   │   └── types/          # TypeScript definitions
│   │       └── nodes.d.ts
│   └── github-pr/
│       └── ...
├── types/                  # Global TypeScript types
│   └── n8n-workflows.d.ts
└── n8n-config.json        # Configuration file

🔧 Global Options

Available on all commands:

• --config <path> - Path to config file (default: n8n-config.json)
• --verbose - Enable verbose logging
• --dry-run - Show what would be done without making changes
• --help - Show help information

💡 Use Cases

Team Collaboration

1. Split workflows into individual files for easier code review
2. Version control each node and connection separately
3. Merge conflicts become manageable with individual files
4. Parallel development on different parts of the same workflow

Code Organization

1. Extract code nodes into separate .js/.ts files
2. Organize complex workflows into logical file structures
3. Reuse common nodes across multiple workflows
4. Generate TypeScript types for better development experience

CI/CD Integration

1. Validate workflows before deployment
2. Automatic packaging in build pipelines
3. Type checking for workflow code
4. Backup creation before updates

📚 Examples

Basic Workflow Management

# Initialize project
npx n8n-workflow-manager init

# Place your n8n workflow JSON files in the n8n/ directory
cp my-workflow.json n8n/

# Split into individual files
npx n8n-workflow-manager split

# Edit files in workflows/ directory
# ...make changes...

# Package back to JSON
npx n8n-workflow-manager package

TypeScript Development

# Generate TypeScript types
npx n8n-workflow-manager types

# Your code nodes can now use proper types
// workflows/my-workflow/nodes/process-data.ts
import { N8nNode, WorkflowContext } from '../types/nodes';

export function processData(context: WorkflowContext): N8nNode {
  // Type-safe workflow development
  return {
    json: {
      processed: true,
      data: context.inputData
    }
  };
}

CI/CD Pipeline

# .github/workflows/n8n-workflows.yml
name: n8n Workflows
on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Validate workflows
        run: npx n8n-workflow-manager package --dry-run
      
      - name: Generate types
        run: npx n8n-workflow-manager types
      
      - name: Type check
        run: npx tsc --noEmit

🛠 Development

To contribute to this project:

1. Clone the repository:

   git clone https://github.com/northfacejmb/n8n-workflow-manager.git
   cd n8n-workflow-manager

2. Install dependencies:

   npm install

3. Run linting:

   npm run lint

4. Test your changes:

   npm test

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

Quick ways to contribute:

• 🐛 Report bugs
• 💡 Request features
• 📖 Improve documentation
• 🔧 Submit pull requests

📄 License

MIT © Jeremy Press

🔗 Links

• 📦 npm Package - Install and use the CLI tool
• 🐙 GitHub Repository - Source code and development
• 🐛 Issue Tracker - Report bugs and request features
• 📚 n8n Documentation - Learn about n8n workflows

---

Made with ❤️ for the n8n community