N8n Agents Project Scaffolder

n8n Project Scaffolder

Generate complete, production-ready n8n project structures from scratch.

Quick Reference

Decision Tree: Which Scaffold?

What are you building?
|
+-- A new n8n server deployment?
|   |
|   +-- Single instance (dev/small team)?
|   |   --> DEPLOYMENT SCAFFOLD (PostgreSQL)
|   |
|   +-- High-traffic / horizontal scaling?
|       --> QUEUE MODE SCAFFOLD (PostgreSQL + Redis + Workers)
|
+-- A custom n8n node package?
|   --> CUSTOM NODE SCAFFOLD
|
+-- Starter workflow files?
    --> WORKFLOW TEMPLATE SCAFFOLD

1. Deployment Scaffold (PostgreSQL + Traefik)

Generated Structure

n8n-deployment/
├── docker-compose.yml       # n8n + PostgreSQL + Traefik
├── .env                     # Environment configuration
├── .env.example             # Template with documentation
├── backup.sh                # Automated backup script
├── restore.sh               # Restore from backup
├── local-files/             # Shared file directory
└── backups/                 # Backup output directory

ALWAYS Include in docker-compose.yml

• PostgreSQL service with named volume (postgres_data)
• n8n service with named volume (n8n_data) mounted at /home/node/.n8n
• Traefik reverse proxy with Let's Encrypt TLS
• Local files bind mount (./local-files:/files)
• Explicit N8N_ENCRYPTION_KEY (NEVER rely on auto-generated key)
• N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true
• N8N_RUNNERS_ENABLED=true
• NODE_ENV=production
• restart: always on all services
• PostgreSQL health check with pg_isready
• n8n depends_on PostgreSQL with condition: service_healthy

ALWAYS Include in .env

# === DOMAIN ===
DOMAIN_NAME=example.com
SUBDOMAIN=n8n
SSL_EMAIL=admin@example.com

# === TIMEZONE ===
GENERIC_TIMEZONE=Europe/Amsterdam
TZ=Europe/Amsterdam

# === DATABASE ===
POSTGRES_USER=n8n
POSTGRES_PASSWORD=CHANGE_ME_STRONG_PASSWORD
POSTGRES_DB=n8n

# === SECURITY (CRITICAL) ===
N8N_ENCRYPTION_KEY=GENERATE_WITH_openssl_rand_hex_32

# === EXECUTION ===
EXECUTIONS_DATA_PRUNE=true
EXECUTIONS_DATA_MAX_AGE=336
EXECUTIONS_DATA_PRUNE_MAX_COUNT=10000

NEVER Do

• NEVER use SQLite for production deployments
• NEVER omit N8N_ENCRYPTION_KEY (losing it = losing ALL credential access)
• NEVER expose PostgreSQL port to the internet
• NEVER use default passwords in production

Full Docker Compose template: references/methods.md

2. Queue Mode Scaffold (Redis + Workers)

Generated Structure

n8n-queue-deployment/
├── docker-compose.yml       # n8n main + workers + PostgreSQL + Redis
├── .env                     # Shared environment configuration
├── .env.example             # Template with documentation
├── backup.sh                # Automated backup script
└── local-files/             # Shared file directory

ALWAYS Include for Queue Mode

• EXECUTIONS_MODE=queue on ALL n8n services (main + workers)
• Redis service with named volume
• Separate n8n-worker service using command: worker
• Same N8N_ENCRYPTION_KEY on ALL instances
• Same n8n Docker image version on ALL instances
• PostgreSQL 13+ (SQLite does NOT support queue mode)
• S3-compatible storage for binary data (N8N_DEFAULT_BINARY_DATA_MODE=s3)
• QUEUE_BULL_REDIS_HOST pointing to Redis service name
• Worker concurrency setting (--concurrency=5)

NEVER Do in Queue Mode

• NEVER use SQLite (queue mode requires PostgreSQL)
• NEVER use different n8n versions across main and workers
• NEVER use different encryption keys across instances
• NEVER use filesystem binary data mode (use S3 for shared access)

Full Queue Mode template: references/methods.md

3. Custom Node Scaffold

Generated Structure

n8n-nodes-<your-name>/
├── package.json             # Node registration with n8n block
├── tsconfig.json            # TypeScript configuration
├── .eslintrc.js             # Linting configuration
├── LICENSE                  # MIT license
├── README.md                # Package documentation
├── credentials/
│   └── ExampleApi.credentials.ts
├── nodes/
│   └── ExampleNode/
│       ├── ExampleNode.node.ts
│       └── ExampleNode.node.json
└── icons/
    └── example.svg

ALWAYS Include in package.json

{
  "name": "n8n-nodes-<your-name>",
  "version": "0.1.0",
  "keywords": ["n8n-community-node-package"],
  "n8n": {
    "n8nNodesApiVersion": 1,
    "credentials": ["dist/credentials/ExampleApi.credentials.js"],
    "nodes": ["dist/nodes/ExampleNode/ExampleNode.node.js"]
  },
  "scripts": {
    "build": "n8n-node build",
    "dev": "n8n-node dev",
    "lint": "n8n-node lint",
    "lint:fix": "n8n-node lint --fix"
  },
  "files": ["dist"],
  "devDependencies": {
    "@n8n/node-cli": "*",
    "typescript": "5.9.2"
  },
  "peerDependencies": {
    "n8n-workflow": "*"
  }
}

Critical Rules

• n8n.nodes and n8n.credentials MUST point to compiled .js files in dist/
• Package name MUST start with n8n-nodes-
• keywords MUST include "n8n-community-node-package"
• ALWAYS use n8n-workflow as a peer dependency (NEVER as a direct dependency)
• ALWAYS use @n8n/node-cli as a dev dependency for build tooling
• NEVER modify incoming data from this.getInputData() directly; clone first

Full custom node templates: references/methods.md

4. Workflow Template Scaffold

Available Templates

Workflow JSON Structure (ALWAYS Follow)

{
  "name": "Workflow Name",
  "nodes": [
    {
      "id": "unique-uuid",
      "name": "Node Display Name",
      "type": "n8n-nodes-base.nodeType",
      "typeVersion": 1,
      "position": [250, 300],
      "parameters": {}
    }
  ],
  "connections": {
    "Source Node Name": {
      "main": [[{ "node": "Target Node Name", "type": "main", "index": 0 }]]
    }
  },
  "settings": {
    "executionOrder": "v1",
    "saveDataErrorExecution": "all",
    "saveDataSuccessExecution": "all"
  }
}

ALWAYS Include in Workflow Templates

• "executionOrder": "v1" in settings
• Error handling via continueOnFail or error workflow reference
• Node positions that do not overlap (increment X by 200 per node)
• Unique node names within each workflow

Full workflow templates: references/examples.md

5. Environment Template Reference

Essential Variables (ALWAYS Set in Production)

Security Variables (ALWAYS Review)

6. Backup Script Requirements

ALWAYS Include in Backup Scripts

• PostgreSQL dump via pg_dump (or docker exec equivalent)
• Workflow export via n8n export:workflow --backup
• Credential export via n8n export:credentials --backup
• Timestamped output directories
• Retention policy (delete backups older than N days)
• Encryption key backup reminder/verification

NEVER Do in Backup Scripts

• NEVER export credentials with --decrypted flag in automated scripts
• NEVER store backups without the corresponding N8N_ENCRYPTION_KEY
• NEVER skip the PostgreSQL dump (it contains execution history)

Full backup script template: references/methods.md

7. Security Defaults Checklist

ALWAYS apply these security defaults when scaffolding ANY n8n project:

• Generate N8N_ENCRYPTION_KEY with openssl rand -hex 32
• Set N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true
• Set N8N_RUNNERS_ENABLED=true (sandboxed Code node execution)
• Set NODE_ENV=production
• Set N8N_BLOCK_ENV_ACCESS_IN_NODE=true (shared environments)
• Exclude dangerous nodes: NODES_EXCLUDE=["n8n-nodes-base.executeCommand"]
• Use HTTPS via reverse proxy (Traefik/nginx/Caddy)
• Set strong PostgreSQL password
• Do NOT expose database ports publicly
• Configure execution data pruning

Reference Links

• Scaffolding Templates & Methods
• Complete Project Examples
• Anti-Patterns & Common Mistakes
• n8n Docker Deployment Docs
• n8n Environment Variables
• n8n Queue Mode Docs
• n8n Custom Node Starter