{"id":17577,"library":"directus","title":"Directus Headless CMS","description":"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.","status":"active","version":"11.17.3","language":"javascript","source_language":"en","source_url":"https://github.com/directus/directus","tags":["javascript","directus","realtime","database","content","api","rest","graphql","app"],"install":[{"cmd":"npm install directus","lang":"bash","label":"npm"},{"cmd":"yarn add directus","lang":"bash","label":"yarn"},{"cmd":"pnpm add directus","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Used for programmatically starting the Directus server. Requires environment variables to be configured.","wrong":"const directus = require('directus'); directus.start();","symbol":"start","correct":"import { start } from 'directus';"},{"note":"Used for programmatically stopping a running Directus server instance gracefully.","wrong":"const { stop } = require('directus');","symbol":"stop","correct":"import { stop } from 'directus';"},{"note":"Type definition for configuring the Directus server when used programmatically. Actual configuration is typically done via environment variables or a config file.","symbol":"DirectusConfig","correct":"import type { DirectusConfig } from 'directus';"}],"quickstart":{"code":"import { start } from 'directus';\nimport dotenv from 'dotenv';\nimport path from 'path';\nimport fs from 'fs';\n\n// Load environment variables from .env file\ndotenv.config();\n\nconst PROJECT_PATH = path.resolve(__dirname, './directus-project');\nconst DB_FILE = path.join(PROJECT_PATH, 'database.sqlite');\n\n// Ensure project directory exists\nif (!fs.existsSync(PROJECT_PATH)) {\n    fs.mkdirSync(PROJECT_PATH, { recursive: true });\n}\n\n// Set required environment variables for a minimal Directus setup\n// Directus will auto-bootstrap a SQLite database and admin user on first run.\nprocess.env.PUBLIC_URL = process.env.PUBLIC_URL ?? 'http://localhost:8055';\nprocess.env.DB_CLIENT = process.env.DB_CLIENT ?? 'sqlite3';\nprocess.env.DB_FILENAME = process.env.DB_FILENAME ?? DB_FILE;\nprocess.env.ADMIN_EMAIL = process.env.ADMIN_EMAIL ?? 'admin@example.com';\nprocess.env.ADMIN_PASSWORD = process.env.ADMIN_PASSWORD ?? 'password';\nprocess.env.SECRET = process.env.SECRET ?? 'a_super_secret_key_that_should_be_long_and_random_for_security';\nprocess.env.PORT = process.env.PORT ?? '8055';\nprocess.env.REFRESH_TOKEN_SECRET = process.env.REFRESH_TOKEN_SECRET ?? 'another_super_secret_key_for_refresh_tokens';\nprocess.env.ACCESS_TOKEN_SECRET = process.env.ACCESS_TOKEN_SECRET ?? 'yet_another_super_secret_key_for_access_tokens';\nprocess.env.KEY = process.env.KEY ?? ''; // Placeholder for process.env.KEY (not always required)\n\nconsole.log('Attempting to start Directus server...');\n\nstart().then(() => {\n  console.log(`Directus server successfully started on ${process.env.PUBLIC_URL}`);\n  console.log(`Access the admin panel at ${process.env.PUBLIC_URL}/admin`);\n  console.log(`Initial Admin User: ${process.env.ADMIN_EMAIL} / ${process.env.ADMIN_PASSWORD}`);\n  console.log('Note: On first run, Directus will initialize the database schema and create the admin user.');\n}).catch((err) => {\n  console.error('Failed to start Directus server:', err);\n  process.exit(1);\n});\n","lang":"typescript","description":"This quickstart demonstrates how to programmatically start a Directus server instance using SQLite, automatically configuring essential environment variables and an admin user for initial setup. It creates a project directory and a database file if they don't exist."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=11.x (impacting >=12.0.0)"},{"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.","message":"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.","severity":"breaking","affected_versions":">=11.17.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=11.16.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=11.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=11.13.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=11.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"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.","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.","error":"Error: Database connection failed"},{"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'`.","cause":"The `SECRET` environment variable, crucial for cryptographic operations, is not set.","error":"Error: Missing environment variable: SECRET"},{"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`.","cause":"Another process is already using the port Directus is trying to bind to (default 8055).","error":"Address already in use :::8055"},{"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.","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.","error":"Error: EACCES: permission denied, open '/path/to/directus-project/database.sqlite'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}