Guida a Directus CMS: Headless CMS Database-First per Sviluppatori

Guida a Directus CMS: Headless CMS Database-First per Sviluppatori

La maggior parte degli headless CMS vuole che tu costruisca il modello dei dati al loro interno. Directus ribalta questo approccio — avvolge il tuo database SQL esistente e ti fornisce API REST e GraphQL immediate senza toccare il tuo schema. Con ~34.5k stelle su GitHub e l'adozione da parte di aziende come Tripadvisor, Adobe e Mercedes-Benz, è una delle opzioni open-source più capaci tra i migliori headless CMS del 2026.

Cos'è Directus CMS?

Directus è un headless CMS open-source che avvolge qualsiasi database SQL esistente con API REST e GraphQL immediate. A differenza di Strapi o Payload, Directus non crea un proprio schema del database — rispecchia il tuo. Supporta 7 database tra cui PostgreSQL, MySQL, MariaDB, SQLite, OracleDB, CockroachDB e MS-SQL, ed è gratuito per le organizzazioni con ricavi inferiori a $5M secondo la documentazione ufficiale di Directus.

Pensalo come uno strato intelligente che si posiziona sopra il tuo database. Hai un database PostgreSQL con 50 tabelle? Punti Directus su di esso e in pochi minuti hai una UI admin completa, controllo degli accessi basato sui ruoli ed endpoint sia REST che GraphQL. Nessuno script di migrazione. Nessuna ristrutturazione dei dati.

Questo è ciò che "database-first" significa in pratica — ed è fondamentalmente diverso dall'approccio code-first di Strapi (dove definisci i tipi di contenuto che generano tabelle nel database) o dall'approccio framework-embedded di Payload CMS (dove il CMS vive dentro la tua app Next.js).

Architettura Database-First Spiegata

Quando abbiamo connesso per la prima volta Directus a un database PostgreSQL esistente per un progetto cliente, la cosa che ci ha sorpreso di più è stata quanto poco setup fosse necessario. Directus analizza lo schema del tuo database — le tabelle diventano "collection", le colonne diventano "field" — e costruisce la sua interfaccia admin da ciò che già esiste.

Questo significa che i tuoi dati non restano mai bloccati in un formato proprietario. Se decidi di smettere di usare Directus domani, il tuo database rimane un normale database SQL. Prova a fare la stessa cosa con Contentful o Sanity, dove i tuoi contenuti vivono sui loro server nel loro formato.

Directus non è solo un CMS. Il team lo posiziona come piattaforma dati componibile — le persone lo usano per BaaS (Backend as a Service), pannelli admin interni e dashboard personalizzati. Il caso d'uso CMS è il più diffuso, ma l'architettura supporta molto di più.

Funzionalità Principali di Directus

Directus offre API REST e GraphQL doppie, permessi granulari basati sui ruoli, automazione Flows integrata, un Data Studio drag-and-drop, gestione degli asset digitali e supporto i18n nativo per oltre 50 lingue. Dalla v11.15 include editing collaborativo e un AI Assistant come funzionalità native — non plugin di terze parti.

Ecco cosa conta di più se stai valutando Directus per un progetto:

API REST e GraphQL Doppie

Entrambe le API sono disponibili contemporaneamente dagli stessi dati, senza configurazione. Non devi scegliere l'una o l'altra — le ottieni entrambe. Il tuo team mobile può usare REST mentre il frontend web usa GraphQL. L'API REST segue un pattern prevedibile (/items/{collection}) e l'endpoint GraphQL si trova a /graphql.

Flows e Automazione

Flows è il sistema di automazione event-driven di Directus, costruito direttamente nell'UI del Data Studio. Puoi attivare workflow su eventi CRUD (elemento creato, aggiornato, eliminato), pianificazioni (in stile cron) o webhook. Le operazioni includono l'invio di email, richieste HTTP, esecuzione di JavaScript personalizzato e trasformazione dei dati.

Per i team che lavorano con l'IA, Directus ha persino un server Model Context Protocol (MCP) nativo — ma ne parliamo nella sezione v11.

Estensioni e Personalizzazione

Il sistema di estensioni supporta hook (gestori di eventi lato server), endpoint personalizzati, pannelli UI, moduli completi e nodi operativi per i Flows. Le estensioni sono costruite con Vue.js per il frontend e Node.js per il backend. La versione v11.0 ha ristrutturato le estensioni da cartelle basate sul tipo a un formato bundled più pulito.

Ecco come Directus si confronta con la concorrenza sulle funzionalità:

Novità in Directus v11 (2025-2026)

Directus v11 ha introdotto il supporto nativo al server MCP (v11.13), un AI Assistant che supporta OpenAI, Anthropic e Gemini (v11.14), editing collaborativo con indicatori di presenza live (v11.15) e versioni bozza globali con permessi di deploy basati sui ruoli (v11.16). Sono tutte funzionalità integrate, non estensioni della community.

È qui che Directus si è mosso più velocemente, ed è la sezione che la maggior parte dei concorrenti ignora completamente. Solo una delle prime sei guide in classifica copre qualcosa di tutto ciò.

Server MCP e AI Assistant

La release v11.13 ha reso Directus uno dei primi CMS con un server MCP nativo. Se usi Claude, ChatGPT o qualsiasi strumento IA compatibile con MCP, può gestire i contenuti Directus direttamente — leggendo collection, creando elementi, aggiornando field — rispettando i tuoi permessi RBAC. Se non conosci MCP, la nostra guida al Model Context Protocol (MCP) spiega il protocollo nel dettaglio.

L'AI Assistant (v11.14) è separato dall'MCP — è un'interfaccia chat integrata dentro il Data Studio che supporta OpenAI, Anthropic, Gemini e persino modelli locali tramite Ollama. Con la v11.16 è diventato multimodale: puoi caricare immagini e PDF direttamente nella chat IA per l'elaborazione.

Editing Collaborativo e Versioni Bozza

L'editing collaborativo è arrivato con v11.15 con indicatori di presenza live (puoi vedere chi sta modificando lo stesso elemento) e blocco a livello di field per prevenire conflitti. La stessa release ha aggiunto un modulo di deploy per Vercel con permessi basati sui ruoli.

La v11.16 ha spinto ulteriormente lo staging dei contenuti con versioni bozza globali. Ogni elemento con versioning ottiene automaticamente una copia bozza. Gli editor possono confrontare le modifiche con la versione live e promuovere le bozze quando sono pronte. I permessi di deploy basati sui ruoli consentono al team editoriale di preparare le modifiche senza pubblicarle accidentalmente in produzione.

Iniziare con Directus (Setup con Docker)

Puoi avviare Directus in locale con Docker in meno di 2 minuti. Crea un file docker-compose.yml con l'immagine directus/directus, imposta la connessione al database e le credenziali admin come variabili d'ambiente, poi esegui docker compose up. Directus si avvia su localhost:8055.

Il setup con Docker ci ha richiesto meno di 2 minuti da zero. Ecco un docker-compose.yml completo con PostgreSQL incluso — non solo il container Directus, ma lo stack completo:

# docker-compose.yml
version: "3"
services:
  database:
    image: postgis/postgis:16-3.4-alpine
    environment:
      POSTGRES_USER: directus
      POSTGRES_PASSWORD: directus
      POSTGRES_DB: directus
    volumes:
      - directus_data:/var/lib/postgresql/data

  directus:
    image: directus/directus:11.16
    ports:
      - "8055:8055"
    depends_on:
      - database
    environment:
      KEY: "your-random-key-here"
      SECRET: "your-random-secret-here"
      ADMIN_EMAIL: "[email protected]"
      ADMIN_PASSWORD: "change-me-please"
      DB_CLIENT: "pg"
      DB_HOST: "database"
      DB_PORT: "5432"
      DB_DATABASE: "directus"
      DB_USER: "directus"
      DB_PASSWORD: "directus"
    volumes:
      - directus_uploads:/directus/uploads

volumes:
  directus_data:
  directus_uploads:

Avvialo:

docker compose up -d

Apri http://localhost:8055, accedi con le credenziali admin che hai impostato e sei nel Data Studio. Da qui puoi creare collection (tabelle), definire field (colonne) e iniziare a gestire i contenuti subito. Le variabili d'ambiente KEY e SECRET vengono usate per la generazione dei token JWT — usa stringhe casuali in produzione, non i placeholder qui sopra.

Interrogare i Dati con il Directus SDK

Il Directus JavaScript SDK fornisce accesso type-safe ai tuoi dati tramite REST e GraphQL. Installa @directus/sdk, crea un client con createDirectus() e usa readItems() per recuperare le collection con filtering, sorting e selezione dei field integrati.

Il pattern componibile dell'SDK ci è sembrato intuitivo dopo aver lavorato con librerie come il client di Supabase. Parti da un client base e aggiungi capacità componendo funzioni:

// lib/directus.ts
import { createDirectus, rest, readItems, createItem } from '@directus/sdk';

const client = createDirectus('http://localhost:8055').with(rest());

// Recupera articoli pubblicati con field specifici
const articles = await client.request(
  readItems('articles', {
    fields: ['id', 'title', 'slug', 'content', 'author.name'],
    filter: {
      status: { _eq: 'published' }
    },
    sort: ['-date_published'],
    limit: 10
  })
);

Creare elementi segue lo stesso pattern:

// Crea un nuovo articolo
const newArticle = await client.request(
  createItem('articles', {
    title: 'Il Mio Nuovo Post',
    slug: 'il-mio-nuovo-post',
    content: '<p>Ciao da Directus.</p>',
    status: 'draft'
  })
);

Per l'autenticazione, scegli tra staticToken() (per comunicazioni server-to-server) e authentication() (per app rivolte agli utenti con flussi di login):

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

// Lato server con token statico
const client = createDirectus('http://localhost:8055')
  .with(staticToken('your-api-token'))
  .with(rest());

Esempi con l'API REST

Ogni metodo SDK ha un endpoint REST equivalente. Se preferisci lavorare direttamente con curl o fetch:

# Recupera articoli pubblicati
curl "http://localhost:8055/items/articles?filter[status][_eq]=published&sort=-date_published&limit=10&fields=id,title,slug"

# Crea un nuovo elemento
curl -X POST "http://localhost:8055/items/articles" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Il Mio Post", "status": "draft"}'

Query GraphQL

Gli stessi dati sono disponibili tramite GraphQL su /graphql:

query {
  articles(
    filter: { status: { _eq: "published" } }
    sort: ["-date_published"]
    limit: 10
  ) {
    id
    title
    slug
    content
    author {
      name
    }
  }
}

Non devi configurare o abilitare GraphQL separatamente — è sempre disponibile insieme a REST.

Directus con Next.js (Integrazione con Framework)

Collegare Directus a Next.js richiede tre passaggi: installa @directus/sdk, crea un client lib/directus.ts e recupera i dati nei tuoi Server Component usando readItems(). Directus restituisce JSON puro, quindi hai il controllo completo sul rendering senza componenti specifici del vendor.

Questa è la parte più pulita del lavorare con Directus. Non c'è nessun adattatore specifico per il framework, nessun componente React Directus, nessun plugin di build. Sono solo dati da recuperare. Se hai già lavorato con qualsiasi API REST in Next.js, sai già come funziona. Per il contesto sulle scelte di framework, vedi il nostro confronto Next.js vs Remix.

Prima, crea il client condiviso (è lo stesso file della sezione SDK, ma configurato per la tua istanza deployata):

// lib/directus.ts
import { createDirectus, rest, staticToken, readItems } from '@directus/sdk';

const directus = createDirectus(process.env.DIRECTUS_URL!)
  .with(staticToken(process.env.DIRECTUS_TOKEN!))
  .with(rest());

export default directus;
export { readItems };

Poi usalo in un Server Component — niente useEffect, niente stati di loading, solo async/await:

// app/blog/page.tsx
import directus, { readItems } from '@/lib/directus';

export default async function BlogPage() {
  const posts = await directus.request(
    readItems('posts', {
      fields: ['id', 'title', 'slug', 'excerpt', 'date_published'],
      filter: { status: { _eq: 'published' } },
      sort: ['-date_published'],
    })
  );

  return (
    <main>
      <h1>Blog</h1>
      {posts.map((post) => (
        <article key={post.id}>
          <h2><a href={`/blog/${post.slug}`}>{post.title}</a></h2>
          <p>{post.excerpt}</p>
          <time>{post.date_published}</time>
        </article>
      ))}
    </main>
  );
}

Fatto. Nessun vendor lock-in. Lo stesso approccio funziona con Astro, Nuxt, SvelteKit o qualsiasi framework capace di fare richieste HTTP. La documentazione ufficiale di Directus include guide specifiche per Astro e Nuxt, ma il pattern è identico: crea il client, chiama readItems(), renderizza.

Prezzi e Licenza di Directus CMS (2026)

Directus è gratuito per il self-hosting con licenza MIT per le organizzazioni con meno di $5M di ricavi annuali o finanziamenti. Sopra questa soglia, per l'uso in produzione è necessaria una licenza commerciale. Directus Cloud parte da $25/mese (Starter) con piani Professional da $49 a $499/mese, secondo la loro pagina dei prezzi.

La Soglia dei $5M di Ricavi

Questo è il singolo fatto di business più importante su Directus, e la maggior parte delle guide lo nasconde o lo salta del tutto. Ecco come funziona:

• Sotto $5M di ricavi annuali o finanziamenti totali: Gratuito per sempre. Licenza MIT. Self-hosting ovunque. Nessuna restrizione sulle funzionalità.
• Sopra $5M in produzione: Hai bisogno di una licenza commerciale. Contatta il team vendite di Directus per i prezzi.
• Sviluppo e test: Sempre gratuito, indipendentemente dalle dimensioni dell'azienda. La soglia si applica solo ai deployment in produzione.

Il valore da $5M include i finanziamenti venture, non solo i ricavi. Quindi una startup in fase seed con $6M di finanziamenti è tecnicamente sopra la soglia. In pratica, Directus non è stato aggressivo nell'applicazione per le aziende in fase iniziale, ma dovresti tenerlo in considerazione nella tua pianificazione.

Piani Cloud

Se non vuoi gestire l'infrastruttura, Directus Cloud gestisce hosting, backup e aggiornamenti:

• Starter: $25/mese — ottimo per progetti piccoli, siti personali
• Professional: $49-$499/mese — si scala con storage, banda e trasformazioni degli asset
• Enterprise: Prezzi personalizzati — SLA, infrastruttura dedicata, supporto prioritario

Nessuna licenza per posto. L'intero team usa lo stesso piano. Confrontalo con Contentful, che addebita per utente (vedi la nostra panoramica sui prezzi di Contentful), o Sanity, che addebita in base all'utilizzo delle API e alla banda del dataset.

Directus vs Strapi vs Payload: Come Si Confrontano

Directus avvolge database esistenti senza migrazione, Strapi genera il proprio schema dai tipi di contenuto, e Payload si integra direttamente nella tua app Next.js. Directus supporta 7 database, Strapi ne supporta 2 e Payload 2. Tutti e tre sono open-source, ma le loro filosofie sono abbastanza diverse.

Avendo costruito progetti sia con Strapi che con Directus, la differenza più grande è il modo in cui pensano al tuo database. Con Strapi definisci i tipi di contenuto nell'UI admin o nel codice, e Strapi crea e gestisce le tabelle del database per te. Con Directus il database è la fonte di verità — Directus lo legge e si adatta.

Quando scegliere Directus: Hai un database esistente, vuoi REST+GraphQL doppie out of the box, o hai bisogno di supportare database meno comuni come OracleDB o CockroachDB.

Quando scegliere Strapi: Vuoi l'ecosistema e la community più ampi, preferisci definire i tipi di contenuto tramite un'UI, o stai partendo da zero senza un database esistente. Leggi la nostra guida completa a Strapi per i dettagli.

Quando scegliere Payload: Vuoi il CMS integrato direttamente nella tua applicazione Next.js, preferisci la configurazione TypeScript-first, o hai bisogno di una Local API che eviti del tutto HTTP. Vedi il nostro approfondimento su Payload CMS per il quadro completo.

Quando NON Usare Directus

Directus non è la scelta giusta se hai bisogno di un page builder visuale, di un framework Next.js strettamente integrato o di un backend NoSQL. Aggiunge anche overhead per progetti semplici dove basterebbe un CMS flat-file o WordPress.

Abbiamo visto team scegliere Directus quando non avrebbero dovuto, e il pattern di solito è uno di questi:

• Hai bisogno di un page builder visuale. Il Data Studio di Directus è eccellente per la gestione di dati strutturati, ma non è un costruttore di siti drag-and-drop. Se l'editing visuale è la tua priorità, guarda Storyblok — vedi la nostra guida a Storyblok per un confronto.
• Sei impegnato con NoSQL. Directus è SQL-only per scelta progettuale. Se i tuoi dati vivono in MongoDB, Payload CMS è la soluzione naturale.
• Il tuo progetto è un blog semplice. Avviare Docker, PostgreSQL e Directus per un blog personale è decisamente eccessivo. WordPress, Astro con file markdown o anche Ghost ti faranno pubblicare in una frazione del tempo.
• Vuoi il CMS nel framework. Se vuoi che il tuo CMS viva dentro la tua codebase Next.js come cittadino di prima classe, Payload lo fa nativamente. Directus è sempre un servizio separato.
• Sei una grande organizzazione. Se la tua azienda supera la soglia dei $5M di ricavi, avrai bisogno di una licenza commerciale per la produzione. Considera quel costo rispetto ad alternative completamente open-source come Strapi o Payload, dove il self-hosting è gratuito indipendentemente dai ricavi.

Nessuno di questi è un difetto — sono scelte progettuali. Directus è una piattaforma dati, non un costruttore di siti web. Conoscere la differenza ti risparmia mesi di frustrazione.

FAQ

Cos'è Directus CMS?

Directus è un headless CMS open-source che avvolge qualsiasi database SQL esistente con API REST e GraphQL immediate. Supporta PostgreSQL, MySQL, MariaDB, SQLite, OracleDB, CockroachDB e MS-SQL. A differenza dei CMS tradizionali, Directus non crea un proprio schema — legge e rispecchia automaticamente la struttura del tuo database esistente.

Directus è davvero gratuito?

Directus è gratuito per il self-hosting con licenza MIT per le organizzazioni con meno di $5M di ricavi annuali o finanziamenti totali. Sopra quella soglia, hai bisogno di una licenza commerciale per l'uso in produzione. Gli ambienti di sviluppo e test sono sempre gratuiti. Directus Cloud, il loro hosting gestito, parte da $25 al mese.

In cosa Directus è diverso da Strapi?

Directus è database-first — avvolge il tuo database SQL esistente senza modificare lo schema. Strapi è code-first — definisci i tipi di contenuto e Strapi genera le tabelle del database. Directus supporta 7 database mentre Strapi ne supporta 2. Entrambi offrono API REST, ma Directus include GraphQL nativo mentre Strapi richiede un plugin.

Quali database supporta Directus?

Directus supporta sette database SQL: PostgreSQL, MySQL, MariaDB, SQLite, OracleDB, CockroachDB e MS-SQL. Si connette al tuo database esistente e analizza lo schema automaticamente. Questo supporto multi-database è unico tra gli headless CMS — la maggior parte dei concorrenti supporta solo uno o due motori di database.

Directus può sostituire WordPress?

Directus può sostituire WordPress per la gestione dei contenuti, specialmente per progetti headless o API-driven. Tuttavia, Directus non ha un frontend integrato, temi o page builder. Dovrai costruire il tuo frontend con un framework come Next.js o Astro. Per blog semplici o siti che necessitano di editing visuale, WordPress rimane più pratico.

Directus ha un editor visuale?

Directus include un Data Studio — una potente UI admin per gestire dati strutturati, costruire dashboard e configurare i permessi. Tuttavia, non ha un page builder visuale o un editor WYSIWYG per siti come Storyblok o WordPress. Directus è progettato per la gestione dei dati, non per la composizione drag-and-drop delle pagine.

Directus va bene per l'e-commerce?

Directus funziona bene come sistema di gestione delle informazioni sui prodotti — puoi modellare cataloghi prodotti, gestire attributi e servire dati tramite API. Tuttavia, non è una piattaforma e-commerce. Non troverai un carrello, un flusso di checkout o l'elaborazione dei pagamenti. Abbinalo a Shopify, Saleor o Medusa per lo strato transazionale.

Posso usare Directus con Next.js?

Sì. Installa il pacchetto @directus/sdk, crea un client che punta alla tua istanza Directus e recupera i dati nei Server Component usando readItems(). Directus restituisce JSON puro, quindi non sono necessari componenti React specifici del vendor. Lo stesso approccio funziona con qualsiasi framework JavaScript inclusi Astro, Nuxt e SvelteKit.

Directus supporta l'editing collaborativo?

Sì, dalla versione 11.15 (febbraio 2026). Directus ha l'editing collaborativo nativo con indicatori di presenza live che mostrano chi sta modificando cosa, e il blocco a livello di field per prevenire conflitti. È una funzionalità integrata, non un plugin. Combinato con le versioni bozza globali in v11.16, i team possono preparare e visualizzare in anteprima le modifiche prima della pubblicazione.

Cos'è il server MCP di Directus?

Directus ha introdotto un server Model Context Protocol nativo nella v11.13 (novembre 2025). MCP consente agli strumenti IA come Claude e ChatGPT di interagire direttamente con i tuoi contenuti Directus — leggendo, creando e aggiornando elementi tramite linguaggio naturale. Il server MCP rispetta i tuoi permessi RBAC esistenti, quindi l'accesso IA segue le stesse regole degli utenti umani.