https://github.com/directus/n8n-nodes-directus
https://github.com/directus/n8n-nodes-directus
Last synced: 3 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/directus/n8n-nodes-directus
- Owner: directus
- License: mit
- Created: 2025-09-23T21:07:45.000Z (9 months ago)
- Default Branch: master
- Last Pushed: 2025-12-05T20:37:29.000Z (6 months ago)
- Last Synced: 2025-12-07T05:40:17.798Z (6 months ago)
- Language: TypeScript
- Size: 486 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
# n8n-nodes-directus
A comprehensive n8n community node package for integrating with Directus CMS.
[n8n](https://n8n.io/) is a [fair-code licensed](https://docs.n8n.io/reference/license/) workflow automation platform.
## Installation
Follow the [installation guide](https://docs.n8n.io/integrations/community-nodes/installation/) in the n8n community nodes documentation.
### Package Name
The package is published as `@directus/n8n-nodes-directus` on npm.
### From npm (when published)
```bash
npm install @directus/n8n-nodes-directus
```
## Usage
### Getting Started
1. **Install the package** (when published):
```bash
npm install @directus/n8n-nodes-directus
# Or using pnpm
pnpm add @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)
- **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](https://ngrok.com/)
### Setup
```bash
# 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
1. **Start n8n with your node loaded**:
```bash
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):
```bash
# macOS with Homebrew
brew install ngrok
# Or download from https://ngrok.com/
```
2. **Start n8n** (in one terminal):
```bash
npm run dev:n8n
```
3. **Start ngrok** (in another terminal):
```bash
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](https://github.com/directus/n8n-nodes-directus/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](https://github.com/directus/n8n-nodes-directus/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](https://docs.n8n.io/integrations/community-nodes/installation/)
- [Directus API Documentation](https://directus.io/docs/api)
## License
MIT License - see [LICENSE](LICENSE) file for details.
## Support
For issues and questions:
- [GitHub Issues](https://github.com/directus/n8n-nodes-directus/issues)
- [Directus Community](https://community.directus.io/)
- [n8n Community](https://community.n8n.io/)