📄 README.md

n8n-nodes-directus

A comprehensive n8n community node package for integrating with Directus CMS.

n8n is a fair-code licensed workflow automation platform.

Installation

Follow the installation guide in the n8n community nodes documentation.

Package Name

The package is published as @directus/n8n-nodes-directus on npm.

From npm (when published)

npm install @directus/n8n-nodes-directus

Usage

Getting Started

Install the package (when published):

npm install @directus/n8n-nodes-directus

   # Or using pnpm
   pnpm add @directus/n8n-nodes-directus

Configure credentials in n8n:

Add your Directus URL (e.g., https://your-directus.app)

Add your Directus API token with appropriate permissions

Use the nodes in your workflows:

Directus Node: For CRUD operations on items, users, and files

Directus Trigger Node: For webhook-based automation

Available Operations

Directus Node

Items:

Create, Create (Raw JSON)

Get, Get (Raw JSON)

Get Many, Get Many (Raw JSON)

Update, Update (Raw JSON)

Delete
Users:

Invite

Get, Get (Raw JSON)

Get Many, Get Many (Raw JSON) with Simplify option

Update, Update (Raw JSON)

Delete
Files:

Upload a File (using binary data from a previous node)

Import a File (from a URL)

Get, Get (Raw JSON)

Get Many, Get Many (Raw JSON) with Simplify option

Update, Update (Raw JSON)

Delete

Directus Trigger Node

Item Events: Trigger on create, update, delete operations in collections
User Events: Trigger on user creation, updates, and deletions
File Events: Trigger on file uploads and updates

Features

Dynamic Field Loading: Automatically loads available collections and fields from your Directus instance
Smart Field Processing: Handles complex field types and relationships
Simplify Option: Returns essential fields only for Users and Files "Get Many" operations
Raw JSON Operations: Full support for raw JSON data/query parameters for advanced use cases (available for all CRUD operations)
Robust Error Handling: Comprehensive error handling with detailed error messages
Webhook Management: Automatic webhook creation and cleanup for trigger nodes
Type Safety: Full TypeScript support with proper type definitions
UX Compliance: Follows n8n community node UX guidelines with proper naming and placeholders

Credentials

Directus API

Configure your Directus instance connection:

Directus URL: Your Directus instance URL (e.g., https://your-directus.app)
Token: Your Directus API token with appropriate permissions

Compatibility

Directus Cloud: Fully supported
Self-hosted Directus: Fully supported
Directus Versions: Compatible with Directus 10.0+

Development

This project uses the official n8n-node CLI tool for development and follows n8n community node standards.

Prerequisites

Node.js 22+
npm 10+
Directus instance for testing (cloud or self-hosted)
ngrok (for webhook testing) - install from ngrok.com

Setup

# Clone the repository
git clone https://github.com/directus/n8n-nodes-directus.git
cd n8n-nodes-directus

# Install dependencies
npm install

# Build the project
npm run build

Quick Start

Start n8n with your node loaded:

npm run dev:n8n

This will:

Link your custom node to n8n

Start n8n development server

Make your Directus nodes available in n8n

Access n8n: Open http://localhost:5678 in your browser

Configure credentials:

Add your Directus API credentials

Test the connection

Create workflows: Use the Directus nodes in your workflows

Testing

Webhook Testing (Requires ngrok)

For testing the Directus Trigger node, you need to expose n8n via a public URL since Directus cannot reach localhost:

Install ngrok (if not already installed):

# macOS with Homebrew
   brew install ngrok

   # Or download from https://ngrok.com/

Start n8n (in one terminal):

npm run dev:n8n

Start ngrok (in another terminal):

ngrok http 5678

This will give you a public URL like https://abc123.ngrok-free.dev

Create a webhook workflow:

Add a Directus Trigger node

Configure the trigger (resource, event, collection)

Activate the workflow

Copy the webhook URL from n8n

Update Directus webhook:

In Directus, go to Settings → Flows

Find the created flow and edit it

Replace localhost:5678 with your ngrok URL

Save the flow

Test the webhook:

Create/update items in Directus

Check if the webhook triggers in n8n

Note: The manual URL replacement step is required because Directus cannot reach localhost URLs directly.

Getting Help

Check the GitHub Issues for known problems
Run pnpm test to verify everything works
Use pnpm test:coverage to see test coverage

Contributing

We welcome feedback and suggestions! Please help us improve this community node:

Reporting Issues

Bug Reports: Use the GitHub Issues page to report bugs
Feature Requests: Submit enhancement ideas through GitHub Issues
Documentation: Help improve our documentation by reporting unclear sections

Issue Guidelines

When reporting issues, please provide:

Detailed description of the problem or feature request
Steps to reproduce (for bugs)
Expected vs actual behavior
Your Directus version and n8n version
Any relevant error messages or logs

Code Contributions

While we appreciate community interest, we maintain this node internally to ensure:

Consistent code quality and style
Proper testing and validation
Alignment with Directus and n8n best practices
Timely maintenance and updates

If you have specific code improvements or bug fixes, please:

Open an issue first describing the problem or improvement
Wait for our team to review and potentially implement the change
Provide detailed information to help us understand the requirement

This approach ensures the node remains reliable, well-tested, and follows n8n community node verification guidelines.

📦 directus / n8n-nodes-directus