Headless en decoupled Drupal

Headless Drupal is een architectuurkeuze, geen upgrade.
Drupal levert de content als data via een API en een aparte applicatie zet die om in pagina's.
Dat is zinvol bij meerdere kanalen of een frontend-stack die er al staat en verspilling bij één website met een redactie die zelf pagina's samenstelt.
Ik breng in kaart welk deel decoupled moet, koppel dat met JSON:API of GraphQL en laat de rest staan waar het hoort.

Wat betekent headless Drupal?

Headless Drupal betekent dat Drupal geen HTML meer aan de bezoeker levert, maar gestructureerde data aan een laag die de weergave verzorgt.
Headless en decoupled worden door elkaar gebruikt en daar beginnen veel projecten fout, want er zitten twee varianten onder met een verschillend prijskaartje.

Fully decoupled

Bij fully decoupled is Drupal alleen nog contentmodel, workflow en redactieomgeving.
Alle publieke HTML komt uit een aparte applicatie, doorgaans een JavaScript-framework met server-side rendering.
Daar staat tegenover dat je zelf opbouwt wat de themalaag normaal meelevert: routing, metatags, canonicals, sitemap, redirects, foutpagina's, taalwissel en preview.
Twee codebases, twee deploypijplijnen, twee upgradepaden.

Progressively decoupled

Bij progressively decoupled blijft Drupal de pagina renderen en neemt een JavaScript-component alleen dat stuk over waar interactiviteit iets oplevert: een zoekinterface met facetten, een configurator, een kaart.
De redactie houdt preview en layout en de semantiek en SEO-basis van de rest van de pagina blijven in Drupal.
Voor de meeste sites is dit de betere keuze, want je betaalt alleen voor de complexiteit die je echt nodig hebt.

Wanneer kies je voor headless Drupal?

Headless is zinvol wanneer de frontend meer dan één afnemer heeft, of al bestond voordat Drupal in beeld kwam.
De aanleiding zit dan buiten de website zelf.
Die afweging werk ik punt voor punt uit in headless Drupal: wanneer wel en wanneer niet.

• ✓ Je levert dezelfde content aan een website, een mobiele app en een derde kanaal en wil niet drie keer redigeren.
• ✓ Je hebt al een frontend-stack en een team dat daarin werkt en Drupal komt erbij als contentbron.
• ✓ Frontend en backend worden door gescheiden teams of leveranciers gebouwd, met een API als afspraak tussen beide.
• ✓ Een deel van je interface is een applicatie en geen pagina en dat hoort niet in een Twig-template.

Wanneer headless vooral kosten toevoegt

Voor een site met één publieke frontend en een redactie die zelf pagina's samenstelt, voegt fully decoupled vooral werk toe zonder winst.
Je bouwt opnieuw wat je al had en betaalt dat twee keer: bij de bouw en in het onderhoud.

De extra kost zit op vier plaatsen: een tweede codebase met eigen afhankelijkheden en updateritme, hosting en monitoring voor twee runtimes, debuggen over twee systemen omdat de eerste vraag bij elke fout is welke laag hem veroorzaakt en je aanwervingen, want je hebt Drupal-kennis én frameworkkennis in hetzelfde team nodig.

Headless maakt een site ook niet automatisch sneller.
Een gecachte Drupal-pagina achter een CDN is vaak sneller dan een bundel die na het laden nog data ophaalt.
Snelheid komt uit caching, beeldformaten en de hoeveelheid code die de browser krijgt, niet uit de architectuurkeuze; waar die winst in Drupal zit, staat in Core Web Vitals voor Drupal.
Lijkt je situatie hierop, dan zeg ik dat, ook als het budget al klaarligt.

JSON:API of GraphQL?

JSON:API is de standaardkeuze, want die zit in core en vraagt geen extra bouwwerk.
Het is sinds Drupal 8.7 onderdeel van core, volgt de JSON:API-specificatie en staat standaard in read-only.
Elke entiteit en bundel krijgt een endpoint zonder dat je iets moet definiëren en met sparse fieldsets en include haal je in één verzoek op wat een pagina nodig heeft.

GraphQL zit niet in core.
Het is een contrib-module; in de huidige 5.x-reeks (4.x is nog een onderhoudsbranch) definieer je het schema zelf in code.
Dat is meer werk vooraf en levert een koppeling die je volledig in de hand hebt, wat betaalt wanneer clients heel verschillende doorsnedes van dezelfde content nodig hebben.

De koppeling is zelden het moeilijkste deel.
Het contentmodel is dat.
Een model dat in Drupal prima werkt kan over een API onbruikbaar zijn, omdat de betekenis in de themalaag zit in plaats van in de velden.

Wat headless doet met je redactie

Het zwaarste verlies bij fully decoupled zit bij de redactie, niet bij de techniek.
Drupal rendert preview met het eigen thema en dat thema is er niet meer.
Een redacteur die een ongepubliceerde versie wil zien zoals die live komt, heeft dus een eigen previewpad in de frontend nodig, met geauthenticeerde verzoeken en de juiste revisie of moderatiestatus.

Layout Builder is het tweede knelpunt.
Die werkt met render arrays en HTML, niet met gestructureerde data, dus over een API krijg je geen bruikbare layoutboom terug.
Je kiest dus: Drupal blijft renderen, of je laat vrije paginaopbouw vallen en werkt met een vast componentcontract.
Dat tweede geeft een consistentere site, maar is een inperking voor wie gewend is te schuiven.

Daarnaast vallen contextuele links en inline bewerken weg en komt er één vraag bij: wie zorgt dat de frontend opnieuw bouwt of zijn cache leegt wanneer een redacteur op publiceren duwt.
Zonder die afspraak staat je site uren achter op je redactie.

Wat headless doet met SEO

Headless is niet slecht voor SEO, maar elk automatisme dat Drupal normaal gratis levert moet je expliciet overnemen.
Hier lopen decoupled projecten stille schade op, want het valt pas op als de posities zakken.

• Rendering: server-side rendering is geen optie maar een voorwaarde, want een pagina die volledig in de browser wordt opgebouwd hangt af van wat de zoekmachine wil renderen.
• Statuscodes: een client-side app geeft makkelijk een 200 terug op een pagina die niet bestaat en redirects uit de Redirect-module bereiken de bezoeker niet meer.
• Metadata: titels, descriptions, canonicals, hreflang en structured data moeten over de API meereizen tot in de head.
• Sitemap en URL's: sitemap en padaliassen zitten in Drupal, dus je frontend houdt dezelfde URL's aan of je verliest je geschiedenis.
• Core Web Vitals: LCP, INP en CLS meten wat de browser krijgt en een grote bundel maakt die cijfers slechter.

Geen reden om headless af te schieten, wel om het volwaardig te begroten.
Meer daarover bij technische SEO en frontend performance.
Zet je een bestaande site om, dan verandert je URL-structuur vaak mee en is dit ook een migratievraagstuk.

Toegankelijkheid verhuist mee naar de frontend

De toegankelijkheid die Drupal in core meebrengt geldt alleen voor wat Drupal zelf rendert, dus in een fully decoupled opzet begin je in de frontend van nul.
Dat weegt zwaarder dan vroeger: de European Accessibility Act, richtlijn 2019/882, is van toepassing sinds 28 juni 2025.
Of hij op jou van toepassing is hangt af van je sector en je aanbod: hij viseert onder andere webshops, bankieren, vervoer en e-boeken, met een uitzondering voor micro-ondernemingen die diensten leveren.
Voor overheidssites geldt richtlijn 2016/2102 en de nationale omzetting.
Laat de precieze verplichting juridisch aftoetsen.
Technisch werk je in beide gevallen naar WCAG 2.2 niveau AA en EN 301 549.

De problemen die ik in decoupled frontends terugvind zijn steeds dezelfde vier.
Bij client-side routing verspringt de focus niet en hoort een schermlezergebruiker niet dat er een nieuwe pagina is.
De documenttitel blijft die van de vorige pagina.
Foutmeldingen uit client-side validatie staan los van hun veld.
En modals houden de focus niet vast, dus je komt met het toetsenbord achter het venster terecht.

Een componentbibliotheek die zichzelf toegankelijk noemt lost dat niet op, want het gedrag ontstaat in hoe je de componenten aan elkaar knoopt.
Testen blijft handwerk met toetsenbord en schermlezer naast tools als Lighthouse en axe DevTools.
De aanpak staat bij digitale toegankelijkheid.

Mijn aanpak: afbakenen, koppelen, vastleggen

1. Afbakenen. Vastleggen welk deel decoupled moet en welk deel niet, op basis van de kanalen, de teams en de redactie.
   Resultaat: een architectuurkeuze met de gevolgen voor preview, SEO en toegankelijkheid erbij, in plaats van een framework dat al gekozen was.
2. Koppelen. Het contentmodel API-bruikbaar maken, JSON:API of GraphQL inrichten, rechten en authenticatie regelen en de cachestrategie plus de invalidatie bij publiceren afspreken.
   Het previewpad hoort hier, niet in een restlijst na livegang.
3. Vastleggen. Een componentcontract tussen backend en frontend, documentatie van de endpoints en tests op de koppeling, zodat je eigen team het kan overnemen.

Ik werk meer dan tien jaar met Drupal, voor universiteiten, overheid en industrie en stap in de bestaande Git-flow en conventies in plaats van er een werkwijze naast te zetten.
Eerder werk staat bij de projecten, onder meer de case van Brighteye.

Wat kost een headless Drupal-traject?

Mijn tarief is 75 tot 95 euro per uur of 650 tot 800 euro per dag, exclusief btw, lager bij lange trajecten en terugkerende klanten.
Belgische Drupal-freelancers afficheren op Malt tussen 400 en 600 euro per dag met een mediaan rond 550 euro, de bredere Belgische IT-freelancemarkt zit rond 710 euro per dag en voor Nederland noemt Freelance.nl 70 tot 90 euro per uur.

Wat een headless traject duurder maakt dan hetzelfde project met een Drupal-thema is geen opslag op het uurtarief, maar de extra scope: een tweede applicatie, preview opnieuw bouwen en de SEO- en toegankelijkheidslaag die je anders meekrijgt.
Progressively decoupled blijft dichter bij een normale bouw.
De opbouw staat bij mijn tarieven en samenwerkingsvormen en gaat het om een nieuw platform zonder decoupled frontend, kijk dan bij Drupal architectuur en ontwikkeling.

Twijfel je of headless bij jouw situatie past?