Directus Headless CMS
raw JSON → 11.17.3 verified Thu Apr 23 auth: no javascript
Directus is an open-source data platform and headless CMS that provides a real-time API (REST and GraphQL) and an intuitive App dashboard for managing content stored in any SQL database. It integrates with existing SQL databases without requiring migrations and supports PostgreSQL, MySQL, SQLite, OracleDB, CockroachDB, MariaDB, and MS-SQL. Directus is designed for extensibility, allowing for white-labeling and customization through its modular platform. The current stable version is 11.17.3, with releases occurring frequently, often weekly or bi-weekly, as indicated by the changelog. Key differentiators include its 'database-first' approach, direct SQL management, and a modern Vue.js no-code dashboard for non-technical users. It can be deployed on-premises, in the cloud, or via one-click services like Railway, offering flexibility for various development and production environments.
Common errors
error Error: Database connection failed ↓
cause Incorrect database connection details in environment variables (e.g., `DB_CLIENT`, `DB_HOST`, `DB_USER`, `DB_PASSWORD`, `DB_DATABASE`) or the database server is not running or accessible.
fix
Verify that your database server is running and accessible from the Directus instance. Double-check all
DB_* environment variables for correct values. For Docker deployments, ensure network connectivity between containers. error Error: Missing environment variable: SECRET ↓
cause The `SECRET` environment variable, crucial for cryptographic operations, is not set.
fix
Set a long, random, and unique string as the
SECRET environment variable. This is critical for production security. Example: SECRET='your-long-random-secret-key-here'. error Address already in use :::8055 ↓
cause Another process is already using the port Directus is trying to bind to (default 8055).
fix
Change the
PORT environment variable to an available port, or stop the process currently using port 8055. For example: PORT=8080 npx directus start. error Error: EACCES: permission denied, open '/path/to/directus-project/database.sqlite' ↓
cause Directus does not have write permissions to the specified directory or file for the SQLite database. This often occurs when using Docker or deploying to restricted file systems.
fix
Ensure that the user running the Directus process has read/write permissions to the
DB_FILENAME (for SQLite) or the directory where it's attempting to create the file. For Docker, map volumes with appropriate user permissions. Warnings
breaking Directus is transitioning its core license from Business Source License (BSL) 1.1 to a custom Monospace Sustainable Core License (MSCL) alongside an updated Innovation Grant, expected to be fully implemented with v12. This new model will introduce software registration keys for both paid and free users (under $5M revenue AND 50 employees) and includes non-compete terms. ↓
fix Review the official Directus community posts and documentation regarding the MSCL and Innovation Grant to understand the new terms and potential requirements for license keys and compliance, especially if your organization exceeds the new free tier thresholds.
breaking Directus v11.17.0 introduced changes related to background data imports and improved build times. Exports previously available from `@directus/` internal packages might have changed due to the adoption of `tsdown`'s `oxc-transform` for improved build performance. ↓
fix Developers using internal Directus package exports in custom extensions should verify compatibility and update import paths if necessary. Consult the full changelog for details on affected packages.
breaking Version 11.16.0 introduced global draft versioning, which standardizes the display name of any existing version with the key `draft` to 'Draft'. While content and functionality remain unchanged, this can affect custom naming conventions. ↓
fix Be aware that custom display names for `draft`-keyed versions will be overwritten. Adjust any documentation or user-facing references to reflect the standardized 'Draft' name. No data migration is required.
breaking Directus 11.0.0 made significant changes to its access control model, moving permissions from roles to policies, which can be attached to roles and directly to users. User permissions are now an aggregate of all attached policies. ↓
fix Carefully review and migrate your existing permission structures to the new policy-based model. Ensure all necessary policies are correctly configured and assigned to roles or users to maintain desired access control.
breaking Starting with Directus v11.13, the `RELATIONAL_TYPES` constant no longer includes non-relational types (presentation and group types). Custom extensions or external code referencing this constant may break. ↓
fix Update any custom code or extensions that rely on `RELATIONAL_TYPES` to remove dependencies on the excluded types. Re-evaluate how these types are handled in your custom logic.
gotcha Directus primarily relies on environment variables for configuration. While configuration files (like `.env`, `.json`, `.yaml`, or `.js`) can be used, there might be precedence issues where configuration files could override environment variables in unexpected ways. ↓
fix Always explicitly define critical configurations using environment variables in production environments. Test thoroughly to understand the precedence order if mixing environment variables and configuration files. Refer to Directus documentation for the exact precedence rules.
Install
npm install directus yarn add directus pnpm add directus Imports
- start wrong
const directus = require('directus'); directus.start();correctimport { start } from 'directus'; - stop wrong
const { stop } = require('directus');correctimport { stop } from 'directus'; - DirectusConfig
import type { DirectusConfig } from 'directus';
Quickstart
import { start } from 'directus';
import dotenv from 'dotenv';
import path from 'path';
import fs from 'fs';
// Load environment variables from .env file
dotenv.config();
const PROJECT_PATH = path.resolve(__dirname, './directus-project');
const DB_FILE = path.join(PROJECT_PATH, 'database.sqlite');
// Ensure project directory exists
if (!fs.existsSync(PROJECT_PATH)) {
fs.mkdirSync(PROJECT_PATH, { recursive: true });
}
// Set required environment variables for a minimal Directus setup
// Directus will auto-bootstrap a SQLite database and admin user on first run.
process.env.PUBLIC_URL = process.env.PUBLIC_URL ?? 'http://localhost:8055';
process.env.DB_CLIENT = process.env.DB_CLIENT ?? 'sqlite3';
process.env.DB_FILENAME = process.env.DB_FILENAME ?? DB_FILE;
process.env.ADMIN_EMAIL = process.env.ADMIN_EMAIL ?? 'admin@example.com';
process.env.ADMIN_PASSWORD = process.env.ADMIN_PASSWORD ?? 'password';
process.env.SECRET = process.env.SECRET ?? 'a_super_secret_key_that_should_be_long_and_random_for_security';
process.env.PORT = process.env.PORT ?? '8055';
process.env.REFRESH_TOKEN_SECRET = process.env.REFRESH_TOKEN_SECRET ?? 'another_super_secret_key_for_refresh_tokens';
process.env.ACCESS_TOKEN_SECRET = process.env.ACCESS_TOKEN_SECRET ?? 'yet_another_super_secret_key_for_access_tokens';
process.env.KEY = process.env.KEY ?? ''; // Placeholder for process.env.KEY (not always required)
console.log('Attempting to start Directus server...');
start().then(() => {
console.log(`Directus server successfully started on ${process.env.PUBLIC_URL}`);
console.log(`Access the admin panel at ${process.env.PUBLIC_URL}/admin`);
console.log(`Initial Admin User: ${process.env.ADMIN_EMAIL} / ${process.env.ADMIN_PASSWORD}`);
console.log('Note: On first run, Directus will initialize the database schema and create the admin user.');
}).catch((err) => {
console.error('Failed to start Directus server:', err);
process.exit(1);
});