An official headless demo for Wagtail
Next.js front-end with Wagtail’s v3 API to fetch and render content
Do you want to see what a headless Wagtail implementation looks like? Now there’s an official demo for that ✨👉️ bakerydemo-headless
How it’s built
It’s a Next.js (React) project, written in TypeScript, using the app router and server-rendered components. It’s fully decoupled from the backend, and the goal was to get to "feature parity" with our main bakery demo project.
It renders the site the exact same as the monolith demo, which you can try in your browser if you want to see what it’s like. And the CMS also works the exact same, with Wagtail’s live preview dynamically rendering the relevant view of the Next.js front-end!
Server-side
The headless site’s backend is actually directly based on the bakery demo, with small configuration and code changes to run the backend only as an API server for the Wagtail content. The API is there primarily for the headless front-end, but can also be reused for other properties / apps in a multi-channel publication use case.
v3 API
The site uses Wagtail’s new API introduced in v8.0, and is fully up-to-date with API improvements introduced in Wagtail 8.1. It’s 95% the built-in API, and one or two extra endpoints for specific page listings. This has huge benefits:
- Much less code to maintain than creating fully custom API endpoints for everything.
- 100% reusable OpenAPI schema, to generate TypeScript type definitions and the API client.
Here’s an example, with very granular types down to StreamField blocks data, all available out of the box. Done with solid typing techniques, with unions where appropriate and the needed discriminator properties:
We know there’s a lot of interest in type hints in Wagtail, and this is a practical example of what it looks like in practice, downstream for users.
This is a huge benefit for teams who want strong guarantees that the site’s data model is correctly reflected in both sides of the stack without having to adopt less mainstream tools like GraphQL. Wagtail’s Wagtail Grapple package still definitely works well for GraphQL users, but we know that’s not for everyone.
If you want to learn more about how the API is working out in practice, do check out Sage Abdullah’s upcoming Wagtail Space talk: How can a 🥷 ninja help 🧑 humans and 🤖 agents talk to 🐦 birds?
