Guia Directus CMS: CMS Headless Database-First para Programadores

Guia Directus CMS: CMS Headless Database-First para Programadores

A maioria dos CMS headless exige que construa o seu modelo de dados dentro do respetivo sistema. O Directus inverte essa lógica: envolve a sua base de dados SQL existente e fornece APIs REST e GraphQL instantâneas sem tocar no seu esquema. Com ~34,5 mil estrelas no GitHub e adoção por empresas como a Tripadvisor, Adobe e Mercedes-Benz, é uma das opções open-source mais capazes entre as melhores opções de CMS headless em 2026.

O Que É o Directus CMS?

O Directus é um CMS headless open-source que envolve qualquer base de dados SQL existente com APIs REST e GraphQL instantâneas. Ao contrário do Strapi ou do Payload, o Directus não cria o seu próprio esquema de base de dados; espelha o seu. Suporta 7 bases de dados, incluindo PostgreSQL, MySQL, MariaDB, SQLite, OracleDB, CockroachDB e MS-SQL, e é gratuito para organizações com menos de 5 milhões de dólares de receita, de acordo com a documentação oficial do Directus.

Pense nele como uma camada inteligente que se situa por cima da sua base de dados. Traz uma base de dados PostgreSQL existente com 50 tabelas, aponta o Directus para ela e, em minutos, tem uma interface de administração completa, controlo de acesso baseado em funções e endpoints REST e GraphQL. Sem scripts de migração. Sem reestruturação de dados.

Isto é o que "database-first" significa na prática, sendo fundamentalmente diferente da abordagem code-first utilizada pelo Strapi (onde define tipos de conteúdo que geram tabelas de base de dados) ou da abordagem incorporada na framework do Payload CMS (onde o CMS vive dentro da sua aplicação Next.js).

Arquitetura Database-First Explicada

Quando conectámos o Directus a uma base de dados PostgreSQL existente para um projeto de cliente, o que nos surpreendeu foi o quão pouco setup foi necessário. O Directus introspeciona o esquema da sua base de dados, as tabelas tornam-se "coleções", as colunas tornam-se "campos" e constrói a sua interface de administração a partir do que já existe.

Isto significa que os seus dados nunca ficam presos num formato proprietário. Se decidir deixar de usar o Directus amanhã, a sua base de dados continua a ser uma base de dados SQL standard. Experimente fazer isso com o Contentful ou o Sanity, onde o seu conteúdo vive nos seus servidores no formato deles.

O Directus também não é apenas um CMS. A equipa posiciona-o como uma plataforma de dados composável; as pessoas usam-no para BaaS (Backend as a Service), painéis de administração internos e dashboards personalizados. O caso de uso de CMS é o mais popular, mas a arquitetura suporta muito mais.

Principais Funcionalidades do Directus

O Directus fornece APIs duplas REST e GraphQL, permissões granulares baseadas em funções, automação Flows integrada, um Data Studio drag-and-drop, gestão de ativos digitais e suporte nativo i18n para mais de 50 idiomas. Desde a v11.15, inclui edição colaborativa e um Assistente de IA como funcionalidades nativas, não como plugins de terceiros.

Eis o que mais importa se estiver a avaliar o Directus para um projeto:

APIs Duplas REST e GraphQL

Ambas as APIs estão disponíveis simultaneamente a partir dos mesmos dados, com zero configuração. Não escolhe uma ou outra; obtém ambas. A sua equipa móvel pode usar REST enquanto o seu frontend web usa GraphQL. A API REST segue um padrão previsível (/items/{collection}) e o endpoint GraphQL reside em /graphql.

Flows e Automação

Os Flows são o sistema de automação orientado por eventos do Directus, integrado diretamente na interface do Data Studio. Pode acionar fluxos de trabalho em eventos CRUD (item criado, atualizado, eliminado), agendamentos (estilo cron) ou webhooks. As operações incluem envio de emails, realização de pedidos HTTP, execução de JavaScript personalizado e transformação de dados.

Para equipas que desenvolvem com IA, o Directus tem até um servidor nativo Model Context Protocol (MCP), mas falaremos mais sobre isso na secção v11.

Extensões e Personalização

O sistema de extensões suporta hooks (manipuladores de eventos do lado do servidor), endpoints personalizados, painéis de UI, módulos completos e nós de operação para Flows. As extensões são construídas com Vue.js para o frontend e Node.js puro para o backend. O lançamento da v11.0 reestruturou as extensões de pastas baseadas em tipos para um formato empacotado mais limpo.

Veja como o Directus se compara à concorrência em termos de funcionalidades:

Novidades no Directus v11 (2025-2026)

O Directus v11 introduziu suporte nativo para servidor MCP (v11.13), um Assistente de IA que suporta OpenAI, Anthropic e Gemini (v11.14), edição colaborativa com indicadores de presença em tempo real (v11.15) e versões de rascunho globais com permissões de implementação baseadas em funções (v11.16). Estas são todas funcionalidades integradas, não extensões da comunidade.

É aqui que o Directus tem avançado mais rapidamente, e é a secção que a maioria dos concorrentes ignora completamente. Apenas um dos seis principais guias classifica alguma coisa disto.

Servidor MCP e Assistente de IA

O lançamento v11.13 tornou o Directus um dos primeiros CMS com um servidor MCP nativo. Se estiver a usar o Claude, ChatGPT ou qualquer ferramenta de IA compatível com MCP, esta pode gerir o seu conteúdo do Directus diretamente, lendo coleções, criando itens, atualizando campos, tudo respeitando as suas permissões RBAC. Se é novo no MCP, o nosso guia Model Context Protocol (MCP) explica o protocolo em detalhe.

O Assistente de IA (v11.14) é separado do MCP; é uma interface de chat integrada dentro do Data Studio que suporta OpenAI, Anthropic, Gemini e até modelos locais através do Ollama. Na v11.16, tornou-se multimodal: pode carregar imagens e PDFs diretamente no chat de IA para processamento.

Edição Colaborativa e Versões de Rascunho

A edição colaborativa foi lançada na v11.15 com indicadores de presença em tempo real (pode ver quem mais está a editar o mesmo item) e bloqueio ao nível do campo para prevenir conflitos. O mesmo lançamento adicionou um módulo de implementação Vercel com permissões de implementação baseadas em funções.

A v11.16 levou o staging de conteúdo mais longe com versões de rascunho globais. Cada item versionado obtém automaticamente uma cópia de rascunho. Os editores podem pré-visualizar alterações em relação à versão ativa e promover rascunhos quando estiverem prontos. As permissões de implementação baseadas em funções significam que a sua equipa de conteúdo pode preparar alterações sem empurrar acidentalmente para produção.

Começar com o Directus (Configuração Docker)

Pode executar o Directus localmente com Docker em menos de 2 minutos. Crie um ficheiro docker-compose.yml com a imagem directus/directus, defina a sua ligação à base de dados e credenciais de administrador como variáveis de ambiente e execute docker compose up. O Directus inicia em localhost:8055.

A configuração Docker demorou-nos menos de 2 minutos a partir de um arranque a frio. Eis um docker-compose.yml completo com PostgreSQL incluído, não apenas o contentor Directus, mas toda a stack:

# 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:

Execute-o:

docker compose up -d

Abra http://localhost:8055, inicie sessão com as credenciais de administrador que definiu e estará no Data Studio. A partir daqui, pode criar coleções (tabelas), definir campos (colunas) e começar a gerir conteúdo imediatamente. As variáveis de ambiente KEY e SECRET são usadas para geração de tokens JWT; use strings aleatórias em produção, não os placeholders acima.

Consultar Dados com o SDK do Directus

O SDK JavaScript do Directus fornece acesso type-safe aos seus dados através de REST e GraphQL. Instale @directus/sdk, crie um cliente com createDirectus() e use readItems() para obter coleções com filtragem, ordenação e seleção de campos integrados.

O padrão composável do SDK pareceu intuitivo depois de trabalhar com bibliotecas como o cliente da Supabase. Começa com um cliente base e adiciona capacidades compondo funções:

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

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

// Fetch published articles with specific fields
const articles = await client.request(
  readItems('articles', {
    fields: ['id', 'title', 'slug', 'content', 'author.name'],
    filter: {
      status: { _eq: 'published' }
    },
    sort: ['-date_published'],
    limit: 10
  })
);

Criar itens segue o mesmo padrão:

// Create a new article
const newArticle = await client.request(
  createItem('articles', {
    title: 'My New Post',
    slug: 'my-new-post',
    content: '<p>Hello from Directus.</p>',
    status: 'draft'
  })
);

Para autenticação, escolhe entre staticToken() (para comunicação servidor-a-servidor) e authentication() (para aplicações voltadas ao utilizador com fluxos de login):

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

// Server-side with static token
const client = createDirectus('http://localhost:8055')
  .with(staticToken('your-api-token'))
  .with(rest());

Exemplos de API REST

Cada método do SDK tem um endpoint REST equivalente. Se preferir trabalhar diretamente com curl ou fetch:

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

# Create a new item
curl -X POST "http://localhost:8055/items/articles" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "My Post", "status": "draft"}'

Consultas GraphQL

Os mesmos dados estão disponíveis através de GraphQL em /graphql:

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

Não precisa de configurar ou ativar o GraphQL separadamente; está sempre disponível juntamente com o REST.

Directus com Next.js (Integração com Framework)

Ligar o Directus ao Next.js requer três passos: instalar @directus/sdk, criar um cliente lib/directus.ts e obter dados nos seus Server Components usando readItems(). O Directus devolve JSON puro, por isso tem controlo total sobre a renderização sem componentes específicos do fornecedor.

Esta é a parte mais limpa de trabalhar com o Directus. Não há adaptador especial de framework, não há componentes React específicos do Directus, não há plugin de build. É apenas obtenção de dados. Se já trabalhou com qualquer API REST no Next.js, já sabe como isto funciona. Para contexto sobre escolhas de framework, veja a nossa comparação Next.js vs Remix.

Primeiro, crie o cliente partilhado (este é o mesmo ficheiro da secção SDK, mas configurado para a sua instância implementada):

// 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 };

Depois, use-o num Server Component, sem useEffect, sem estados de carregamento, apenas 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>
  );
}

É tudo. Sem lock-in de fornecedor. A mesma abordagem funciona com Astro, Nuxt, SvelteKit ou qualquer framework que possa fazer pedidos HTTP. A documentação oficial do Directus inclui guias específicos de framework para Astro e Nuxt se os quiser, mas o padrão é idêntico: criar cliente, chamar readItems(), renderizar.

Preços e Licenciamento do Directus CMS (2026)

O Directus é gratuito para autoalojamento sob licença MIT para organizações com menos de 5 milhões de dólares de receita anual ou financiamento. Acima de 5 milhões de dólares, é necessária uma licença comercial para uso em produção. O Directus Cloud começa em 25 USD/mês (Starter) com planos Professional de 49-499 USD/mês, de acordo com a página de preços.

O Limiar de Receita de 5 Milhões de Dólares

Este é o facto comercial mais importante sobre o Directus, e a maioria dos guias ou o enterra ou ignora-o completamente. Eis como funciona:

• Menos de 5 milhões de dólares de receita anual ou financiamento total: Gratuito para sempre. Licença MIT. Autoaloje em qualquer lugar. Sem restrições de funcionalidades.
• Mais de 5 milhões de dólares em produção: Precisa de uma licença comercial. Contacte a equipa comercial do Directus para preços.
• Desenvolvimento e teste: Sempre gratuito, independentemente do tamanho da empresa. O limiar aplica-se apenas a implementações de produção.

O número de 5 milhões de dólares inclui financiamento de venture capital, não apenas receita. Portanto, uma startup em fase seed com 6 milhões de dólares em financiamento cai tecnicamente acima do limiar. Na prática, o Directus não tem sido agressivo na aplicação para empresas em fase inicial, mas deve fatorar isto no seu planeamento.

Planos Cloud

Se não quiser gerir infraestrutura, o Directus Cloud gere alojamento, backups e atualizações:

• Starter: 25 USD/mês, bom para pequenos projetos, sites pessoais
• Professional: 49-499 USD/mês, escala com armazenamento, largura de banda e transformações de ativos
• Enterprise: Preço personalizado, SLA, infraestrutura dedicada, suporte prioritário

Sem licenciamento por assento. Toda a sua equipa usa o mesmo plano. Compare isso com o Contentful, que cobra por utilizador (veja a nossa análise de preços do Contentful), ou o Sanity, que cobra com base no uso da API e largura de banda do dataset.

Directus vs Strapi vs Payload: Comparação

O Directus envolve bases de dados existentes sem migração, o Strapi gera o seu próprio esquema a partir de tipos de conteúdo e o Payload incorpora-se diretamente na sua aplicação Next.js. O Directus suporta 7 bases de dados, o Strapi suporta 2 e o Payload suporta 2. Todos os três são open-source, mas as suas filosofias são bastante diferentes.

Tendo construído projetos com ambos Strapi e Directus, a maior diferença é como pensam na sua base de dados. Com o Strapi, define tipos de conteúdo na UI de administração ou código, e o Strapi cria e gere as tabelas da base de dados para si. Com o Directus, a base de dados é a fonte da verdade; o Directus lê-a e adapta-se.

Quando escolher o Directus: Tem uma base de dados existente, quer REST+GraphQL duplos pronto a usar ou precisa de suportar bases de dados menos comuns como OracleDB ou CockroachDB.

Quando escolher o Strapi: Quer o maior ecossistema e comunidade, prefere definir tipos de conteúdo através de uma UI ou está a começar do zero sem uma base de dados existente. Leia o nosso guia completo do Strapi para detalhes.

Quando escolher o Payload: Quer o CMS incorporado diretamente na sua aplicação Next.js, prefere configuração TypeScript-first ou precisa de uma API Local que salte completamente o HTTP. Veja a nossa análise profunda do Payload CMS para o quadro completo.

Quando NÃO Usar o Directus

O Directus não é a escolha certa se precisar de um construtor visual de páginas, de uma framework Next.js fortemente integrada ou de um backend NoSQL. Também adiciona sobrecarga para projetos simples onde um CMS de ficheiros planos ou WordPress seria suficiente.

Vimos equipas escolherem o Directus quando não deveriam, e o padrão é geralmente um destes:

• Precisa de um construtor visual de páginas. O Data Studio do Directus é excelente para gestão de dados estruturados, mas não é um construtor de sites drag-and-drop. Se a edição visual é a sua prioridade, olhe para o Storyblok; veja o nosso guia do Storyblok para ver como se compara.
• Está comprometido com NoSQL. O Directus é apenas SQL por design. Se os seus dados vivem em MongoDB, o Payload CMS é a escolha natural.
• O seu projeto é um blog simples. Montar Docker, PostgreSQL e Directus para um blog pessoal é um exagero sério. WordPress, Astro com ficheiros markdown ou até mesmo Ghost permitir-lhe-ão publicar numa fração do tempo.
• Quer CMS-na-framework. Se quer que o seu CMS viva dentro da sua codebase Next.js como um cidadão de primeira classe, o Payload faz isso nativamente. O Directus é sempre um serviço separado.
• É uma grande organização. Se a sua empresa excede o limiar de receita de 5 milhões de dólares, precisará de uma licença comercial para produção. Fatorize esse custo contra alternativas totalmente open-source como Strapi ou Payload, onde o autoalojamento é gratuito independentemente da receita.

Nenhum destes são falhas; são decisões de design. O Directus é uma plataforma de dados, não um construtor de sites. Saber a diferença poupa-lhe meses de frustração.

FAQ

O que é o Directus CMS?

O Directus é um CMS headless open-source que envolve qualquer base de dados SQL existente com APIs REST e GraphQL instantâneas. Suporta PostgreSQL, MySQL, MariaDB, SQLite, OracleDB, CockroachDB e MS-SQL. Ao contrário dos CMS tradicionais, o Directus não cria o seu próprio esquema; lê e espelha automaticamente a estrutura da sua base de dados existente.

O Directus é realmente gratuito?

O Directus é gratuito para autoalojamento sob uma licença MIT para organizações com menos de 5 milhões de dólares de receita anual ou financiamento total. Acima desse limiar, precisa de uma licença comercial para uso em produção. Ambientes de desenvolvimento e teste são sempre gratuitos. O Directus Cloud, o seu alojamento gerido, começa em 25 dólares por mês.

Como é que o Directus difere do Strapi?

O Directus é database-first; envolve a sua base de dados SQL existente sem modificar o esquema. O Strapi é code-first; define tipos de conteúdo e o Strapi gera tabelas de base de dados. O Directus suporta 7 bases de dados enquanto o Strapi suporta 2. Ambos oferecem APIs REST, mas o Directus inclui GraphQL nativo enquanto o Strapi requer um plugin.

Que bases de dados suporta o Directus?

O Directus suporta sete bases de dados SQL: PostgreSQL, MySQL, MariaDB, SQLite, OracleDB, CockroachDB e MS-SQL. Conecta-se à sua base de dados existente e introspeciona o esquema automaticamente. Este suporte multi-base de dados é único entre os CMS headless; a maioria dos concorrentes suporta apenas um ou dois motores de base de dados.

O Directus pode substituir o WordPress?

O Directus pode substituir o WordPress para gestão de conteúdo, especialmente para projetos headless ou orientados por API. No entanto, o Directus não tem frontend, temas ou construtor de páginas integrados. Precisará de construir o seu próprio frontend com uma framework como Next.js ou Astro. Para blogs simples ou sites que necessitam de edição visual, o WordPress permanece mais prático.

O Directus tem um editor visual?

O Directus inclui um Data Studio, uma poderosa UI de administração para gerir dados estruturados, construir dashboards e configurar permissões. No entanto, não tem um construtor visual de páginas ou editor de site WYSIWYG como o Storyblok ou o WordPress. O Directus é desenhado para gestão de dados, não para composição de páginas drag-and-drop.

O Directus é bom para e-commerce?

O Directus funciona bem como um sistema de Gestão de Informação de Produto; pode modelar catálogos de produtos, gerir atributos e servir dados via APIs. No entanto, não é uma plataforma de e-commerce. Não obterá um carrinho de compras, fluxo de checkout ou processamento de pagamentos. Combine-o com Shopify, Saleor ou Medusa para a camada transacional.

Posso usar o Directus com Next.js?

Sim. Instale o pacote @directus/sdk, crie um cliente apontando para a sua instância Directus e obtenha dados em Server Components usando readItems(). O Directus devolve JSON puro, por isso não são necessários componentes React específicos do fornecedor. A mesma abordagem funciona com qualquer framework JavaScript, incluindo Astro, Nuxt e SvelteKit.

O Directus suporta edição colaborativa?

Sim, desde a versão 11.15 (fevereiro de 2026). O Directus tem edição colaborativa nativa com indicadores de presença em tempo real que mostram quem está a editar o quê e bloqueio ao nível do campo para prevenir conflitos. Esta é uma funcionalidade integrada, não um plugin. Combinado com versões de rascunho globais na v11.16, as equipas podem preparar e pré-visualizar alterações antes de publicar.

O que é o servidor MCP do Directus?

O Directus introduziu um servidor nativo Model Context Protocol na v11.13 (novembro de 2025). O MCP permite que ferramentas de IA como o Claude e o ChatGPT interajam diretamente com o seu conteúdo Directus, lendo, criando e atualizando itens através de linguagem natural. O servidor MCP respeita as suas permissões RBAC existentes, por isso o acesso da IA segue as mesmas regras que os utilizadores humanos.