Headless architecture — separating the content management layer (backend) from the presentation layer (frontend) — has become the standard for serious web projects. But choosing the right components marks the difference between an elegant architecture and a source of unnecessary complexity.

The Astro + Directus combination is the one we use at Marfcode for most content-driven projects: corporate sites, information portals, catalog e-commerce, corporate blogs. This article explains why and how it works in practice.

The Problem with Traditional Architectures

A traditional WordPress site is a monolith: the CMS manages content, application logic, templates, and rendering in the same application. It works, but it has structural limits:

Performance depends on the PHP server executing logic at every request
Security is exposed to vulnerabilities of the core and plugins
Scalability requires dedicated server infrastructure
The frontend is bound to the CMS templates

Headless architecture solves these problems by separating roles: the CMS deals only with data (and exposes it via API), the frontend consumes it and produces optimized HTML. The two layers can scale, update, and deploy independently.

Why Astro for the Frontend

Islands Architecture: JavaScript Only Where Needed

The fundamental principle of Astro is that most web pages don’t need interactive JavaScript everywhere. A product page has an interactive image carousel (needs JavaScript) and descriptive text (doesn’t need JavaScript). An article has dynamic comments (needs JavaScript) and the body of the article (doesn’t need JavaScript).

Astro calls “islands” the interactive components in a sea of static HTML. Only the islands receive JavaScript. The rest is pure markup, served directly from the CDN with no runtime computational cost.

The practical result: an Astro site with Directus as the data source often produces Lighthouse performance scores between 95 and 100 on performance, SEO, and accessibility — without aggressive manual optimizations.

Multi-Framework Support

Astro is agnostic to the islands’ framework: you can use Svelte, React, Vue, or Solid components for interactive parts, keeping the rest in native Astro. This means existing components written in React can be reused without rewriting — a pragmatic choice that lowers the migration cost from existing architectures.

Native Integration with Headless CMS

Astro has official integrations with dozens of headless CMSs. With Directus, the flow is straightforward: at build time (or with ISR), Astro fetches content from the Directus API, generates static HTML pages, and pushes them to the CDN. The user receives pre-rendered HTML, not an empty page waiting for JavaScript.

Content Collections

For structured content (blogs, documentation, news), Astro has a Content Collections system with type validation via Zod. This guarantees type safety between the data in Directus and the template that renders it — eliminating an entire category of runtime bugs.

Why Directus as a Headless CMS

Database-First, Not Rigid Schema

Directus works in reverse compared to most CMSs: it is installed on top of an existing SQL database (PostgreSQL, MySQL, SQLite) and automatically generates REST and GraphQL APIs for each table. There is no predefined “content model” to start from: the data model is exactly what the project needs.

This has concrete consequences:

The customer is not tied to the vendor: the data is in a standard SQL database. If in five years you want to change CMS or build a different application on top of the same data, it’s possible without complex migrations.

The data model adapts to the business: you can create complex relationships between entities, computed fields, custom views — exactly like in a relational database, with the visual interface of a CMS.

The admin panel is configurable: Directus doesn’t have a fixed “content editor”. The panel can be configured to resemble any management software — with custom fields, custom layouts, approval workflows, granular roles, and permissions.

Flexible API

Directus exposes each resource via REST and GraphQL with filters, sorting, pagination, and relationships in a single call. No additional GraphQL layer is needed for complex queries: ?filter[status][_eq]=published&fields=*,author.name,categories.title is a REST call that returns normalized data with relationships included.

For frontends like Astro that fetch data at build time, this flexibility reduces the number of API calls needed and the complexity of the data fetching layer.

Self-Hosted or Cloud

Directus can be self-hosted (on a VPS, on Docker, on Cloudflare with adaptations) or used as a managed cloud service. For most SMEs, the self-hosted version on a €20–40/month VPS covers any content need without recurring costs related to data volume or API calls.

The Complete Architecture: How They Connect

Editor (Directus Admin)
        ↓
  Directus API (REST/GraphQL)
        ↓
  Astro (build time fetch)
        ↓
  Static HTML + JS Islands
        ↓
  Cloudflare Pages (global CDN)
        ↓
  User (<50ms global latency)

The flow of a content update is:

The editor modifies or publishes content in the Directus panel
A Directus webhook notifies Cloudflare Pages
Cloudflare Pages starts a new Astro build
Astro fetches the updated content from the Directus API
Generates updated static HTML pages
Distributes them on the global Cloudflare CDN

The time between content publication and availability on the site is typically 2–4 minutes for a medium-sized site. For sites with thousands of pages where a complete rebuild would be slow, ISR (Incremental Static Regeneration) is used to regenerate only the modified pages.

Concrete Advantages for the Customer

Intrinsic security: the public site is static HTML on CDN — there is no exposed application server, no live database queries, no attack surface for SQL injection or plugin exploits. Directus runs separately, accessible only from the admin panel with authentication.

Guaranteed performance: HTML pre-rendered on a global CDN. TTFB is under 100ms from any geographic location. It doesn’t depend on a server that “must scale”.

Editor autonomy: the Directus panel is configurable to be intuitive for non-technical users. Editors publish content without touching code, without breaking layouts, without going through the technical team for every change.

Low infrastructure costs: Cloudflare Pages has a generous free plan and a $20/month Pro plan that covers almost all SME projects. Self-hosted Directus on VPS costs €20–40/month. The total infrastructure for a medium-complexity site: less than €60/month.

When This Architecture Is Not the Right One

The Astro + Directus architecture is not suitable when:

The site has highly personalized content for the user in real-time (dynamic web applications, dashboards, social networks)
The rebuild time is unacceptable for the update frequency (real-time news with hundreds of updates per day)
There is no defined publication process (if content changes every hour, a more granular SSR or ISR approach is better)

For these cases, SvelteKit with Directus (in SSR or API-first mode) is the appropriate alternative in the same ecosystem.

Conclusion

Astro + Directus is not the most widespread combination in the Italian web agency market — and this is exactly one of the reasons why we use it. It produces superior technical results compared to traditional approaches, with low infrastructure costs and real autonomy for the customer in content management.

It’s a choice that requires specific skills. It’s not installing a WordPress theme. But for a customer who wants a high-performance, secure, and maintainable digital asset over time, the comparison with alternatives is unforgiving.

→ Talk to Marfcode about your next web project

Astro and Directus: How to Build a High-Performance Headless Site

OUR GUIDES