Directus Skill

Directus is an open-source headless CMS and backend-as-a-service that wraps any SQL database with instant REST and GraphQL APIs, plus a no-code Data Studio for content management. It's built with Node.js and Vue.js, supports PostgreSQL, MySQL, SQLite, MariaDB, MS-SQL, OracleDB, and CockroachDB, and is fully extensible.

How to Use This Skill

This skill is organized into focused reference files. Read the relevant reference before answering:

Always read the relevant reference file before generating code or instructions. For complex questions spanning multiple topics, read multiple references.

Quick-Reference Essentials

These are the most common patterns you'll need. For anything beyond these basics, consult the reference files.

Install the SDK

npm install @directus/sdk

Create a Client (TypeScript)

import { createDirectus, rest, staticToken } from '@directus/sdk';

// Define your schema for type safety
interface MySchema {
  posts: Post[];
  categories: Category[];
  global: GlobalSettings; // singleton (not an array)
}

interface Post {
  id: number;
  title: string;
  content: string;
  status: string;
  category: number | Category;
}

interface Category {
  id: number;
  name: string;
}

interface GlobalSettings {
  site_title: string;
  description: string;
}

const client = createDirectus\x3CMySchema>('https://your-directus-url.com')
  .with(staticToken('your-token'))
  .with(rest());

Read Items

import { readItems, readItem, readSingleton } from '@directus/sdk';

// Get all posts
const posts = await client.request(readItems('posts'));

// Get one post with relational data
const post = await client.request(readItem('posts', 1, {
  fields: ['*', { category: ['name'] }],
}));

// Get singleton
const global = await client.request(readSingleton('global'));

Astro Quick Setup

// src/lib/directus.ts
import { createDirectus, rest } from '@directus/sdk';
const directus = createDirectus(import.meta.env.DIRECTUS_URL).with(rest());
export default directus;

Docker Quick Start

# docker-compose.yml
services:
  directus:
    image: directus/directus:latest
    ports:
      - 8055:8055
    volumes:
      - ./database:/directus/database
      - ./uploads:/directus/uploads
      - ./extensions:/directus/extensions
    environment:
      SECRET: 'your-random-secret'
      ADMIN_EMAIL: '[email protected]'
      ADMIN_PASSWORD: 'your-password'
      DB_CLIENT: 'sqlite3'
      DB_FILENAME: '/directus/database/data.db'
      WEBSOCKETS_ENABLED: 'true'

Key Concepts to Remember

• Composable Client: The SDK client starts empty — you add features with .with(rest()), .with(authentication()), .with(realtime()), .with(staticToken()).
• Schema Typing: Always define a TypeScript schema interface for type-safe SDK usage. Regular collections are arrays, singletons are singular types.
• Access Policies: New collections are private by default. You must configure public read access or use authentication tokens.
• Directus Assets: Images/files are served at {DIRECTUS_URL}/assets/{file-id} with optional transformation query params like ?width=500&format=webp.
• Flows vs Extensions: Flows are no-code automations configured in the Data Studio. Extensions are code-based additions (hooks, endpoints, etc.) that extend Directus itself.
• Environment Variables: Directus is heavily configured via env vars — DB_CLIENT, SECRET, CORS_ENABLED, AUTH_PROVIDERS, etc.