npm package: @skriptfabrik/n8n-nodes-directus
Description: n8n community node package for Directus CMS integration
Author: skriptfabrik GmbH
Latest version: 1.0.4

# 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 `@skriptfabrik/n8n-nodes-directus` on npm.

### From npm (when published)

```bash
npm install @skriptfabrik/n8n-nodes-directus
```

## Usage

### Getting Started

1. **Install the package** (when published):

   ```bash
   npm install @skriptfabrik/n8n-nodes-directus

   # Or using pnpm
   pnpm add @skriptfabrik/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/skriptfabrik/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/skriptfabrik/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/skriptfabrik/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/skriptfabrik/n8n-nodes-directus/issues)
- [Directus Community](https://community.directus.io/)
- [n8n Community](https://community.n8n.io/)