Description

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

1. Install the package (when published):

   npm install @directus/n8n-nodes-directus
   

2. Configure credentials in n8n:
– Add your Directus URL (e.g., https://your-directus.app)
– Add your Directus API token with appropriate permissions

3. 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)
• Directus Error Messages: Errors show the message Directus returned (e.g. Value "Hello" for field "title" in collection "posts" has to be unique.), its error code, the HTTP status, and which input item failed
• 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

Error Output

When a node’s On Error setting is Continue, each failed item is output in place of its result:

{
	"error": "Value "Hello" for field "title" in collection "posts" has to be unique.",
	"details": {
		"httpCode": "400",
		"code": "RECORDNOTUNIQUE",
		"errors": [
			{
				"message": "Value "Hello" for field "title" in collection "posts" has to be unique.",
				"extensions": {
					"code": "RECORDNOTUNIQUE",
					"collection": "posts",
					"field": "title",
					"value": "Hello"
				}
			}
		]
	}
}

details is included when the request got an HTTP response. With Continue (using error output), failed items go to the error output as { "error": "..." } without details, because n8n 1.x and 2.x before 2.36 only route items with that exact shape to the error output.

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.16+ (required by current n8n for npm run dev:n8n; use nvm if needed)
• 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
Use the Node version from .nvmrc (22.16+)
nvm install
nvm use
Install dependencies
npm install
Build the project
npm run build

Quick Start

1. 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

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

3. Configure credentials:
– Add your Directus API credentials
– Test the connection

4. 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:

1. Install ngrok (if not already installed):

   # macOS with Homebrew
   brew install ngrok
   # Or download from https://ngrok.com/
   

2. Start n8n (in one terminal):

   npm run dev:n8n
   

3. Start ngrok (in another terminal):

   ngrok http 5678
   

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

4. Create a webhook workflow:
– Add a Directus Trigger node
– Configure the trigger (resource, event, collection)
– Activate the workflow
– Copy the webhook URL from n8n

5. 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

6. 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 npm test to verify everything works
• Use npm run test:coverage to see test coverage

Contributing

We welcome feedback and suggestions!

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:

1. Open an issue first describing the problem or improvement
2. Wait for our team to review and potentially implement the change
3. 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.

Resources

• n8n Community Nodes Documentation
• Directus API Documentation

License

MIT License – see LICENSE file for details.

Support

For issues and questions:

• GitHub Issues
• Directus Community
• n8n Community