A Look Under the Hood of Lupus Decoupled Drupal

Lupus Decoupled Drupal is reshaping the way developers use headless Drupal by solving a core problem. Most decoupled approaches sacrifice key Drupal features like caching, authentication, and editorial previews. Lupus Decoupled keeps those features intact by letting Drupal stay in control of rendering while handing off the UI to modern JavaScript frameworks like Vue or React. This setup gives teams the best of both worlds without compromise.

The system works by turning Drupal pages into structured trees of custom elements delivered as JSON. These map directly to frontend components, making it easy for developers to build modular, flexible interfaces. With support for low-code configuration, built-in caching, and seamless integration with Nuxt, Lupus Decoupled offers a fast and efficient development experience that does not require deep Drupal or JavaScript expertise.

To understand what sets Lupus Decoupled apart and how it works under the hood, Thomas Alias. K, former sub-editor at The DropTimes, spoke with Wolfgang Ziegler, Managing Director and CTO of drunomics and the creator of Lupus Decoupled. In this in-depth interview, Wolfgang explains the technical foundation, key features, and future direction of a project that is changing how Drupal fits into modern web development.

TDT [1]: What sets Lupus Decoupled apart from other decoupled Drupal solutions, and how does it compare to alternatives like Next.js for headless Drupal?

Wolfgang Ziegler: The ultimate goal of Lupus Decoupled Drupal is to enable frontend-devs to use a modern frontend framework, while keeping as many of Drupal’s features as possible. With a regular Decoupled Drupal approach, the frontend takes over control and queries the backend API to get its data, which leads to the loss of many Drupal’s built-in features like authentication on the frontend, editorial previews or Drupal’s powerful page-level caching capabilities.

With Lupus Decoupled Drupal, Drupal stays in control and renders pages into a high-level tree of components (custom elements), which the frontend framework renders. That way, the mentioned features like editorial previews or page-level caching stay intact.

While this makes for a great solution for frontend developers who want a powerful backend, the ease of using Nuxt and Vue does not require any JavaScript development experience for building sites. You can just write your HTML, CSS, and (optional) JavaScript in a single-file-component, like in a template. That way, it’s also a great solution for front-enders who enjoy working with a modern stack, but don’t necessarily want to dive into JavaScript development.

TDT [2]: Can you walk us through the process of configuring Drupal’s API output using Lupus Decoupled's low-code approach? How much customization is possible without writing custom PHP?

Wolfgang Ziegler: For typical sites, there is no need to write code for Drupal. The custom elements UI module, which is part of Lupus Decoupled Drupal, provides the UI for customizing the API output, such that the frontend can take the data and render it. The idea is to leverage Drupal site-building in the backend, and focus on providing great experiences in the frontend. Moreover, modern frontend frameworks offer plenty of customization options and e.g. can easily integrate further APIs or external systems, such that even in many more complex cases it’s sufficient to customize the frontend.

The way the API customization works is via entity view modes. Just like regular Drupal, Lupus Decoupled builds upon entity view modes for rendering entities. It introduces a new “Manage custom element” screen next to the regular “Manage display” tab for entities. On this screen, you can configure the custom element API output for your entities with formatters for fields, much like you know it from traditional Drupal, but with more options to output pure data that the frontend can consume and render.  This way, frontend developers may simply configure the data they need and render it. Additionally, there is support for Views, and of course, the regular APIs like JSON-API and REST are available as well.

TDT [3]: One of Lupus Decoupled’s strengths is seamless authentication and editorial control in the frontend. How is this achieved under the hood, and what security considerations come into play?

Wolfgang Ziegler: This is achieved by forwarding the session cookie to the backend, preserving Drupal's authentication system and security. Lupus Decoupled supports embedding Drupal forms in the frontend by forwarding requests to Drupal and rendering responses through the frontend. Existing security measures like CSRF tokens continue to function, eliminating potential challenges - Drupal keeps us covered! This feature allows Lupus Decoupled to reuse the existing user login form on the frontend, enabling users to login and access authenticated pages, including editorial previews. This approach maintains Drupal's robust authentication solutions without needing to rebuild them in the frontend.

TDT [4]: How does the integration with Nuxt improve the developer experience compared to other frontend frameworks, and are there any key advantages in using Vue over React for a decoupled Drupal setup?

Wolfgang Ziegler: While both Vue and React are very capable and powerful frameworks, Vue.js is very beginner-friendly thanks to its web-standard-oriented approach. You can basically start by learning its templating syntax while gradually using and learning more features as suiting. So it is easy for everyone to modify HTML, but at the same time it becomes easy to develop interactive JavaScript solutions since there is no barrier jumping from Twig to modern JavaScript anymore.

However, for those preferring React, there is also a Next.js proof of concept frontend implementation, which would make it easy to get started with React. The solution really allows the frontend to be built with the technology of choice, it’s just that the provided starters work with Nuxt by default.

TDT [5]: Performance is a major concern in decoupled architectures. How does Lupus Decoupled optimize rendering speeds, API calls, and frontend performance while keeping everything in sync with Drupal's caching mechanisms?

Wolfgang Ziegler: First off, by having Drupal compose pages, Drupal’s cache metadata and page-level caching solutions simply stay working as with traditional Drupal. That makes it very easy to integrate with a CDN or Varnish for caching.  Second, by having all page data available with the first API call, the solution removes the need for multiple API calls, often leading to a slow waterfall of dependent calls. Third, Nuxt is amazingly fast with server-rendering initial responses. Lastly, Nuxt brings its own suite of performance goodies, like link-prefetching and lazy-loading capabilities for JavaScript chunks. Additionally, client-side navigation removes the need for full-page reloads when users navigate, which makes websites feel even faster!

TDT [6]: With its multi-frontend support, what challenges does Lupus Decoupled solve when switching between different frontends, and how does it maintain consistency across different JavaScript frameworks?

Wolfgang Ziegler: It doesn't. The majority of the solution is implemented on the backend, while the frontend simply makes an API call to get the page data and render the result. Since the rendering is framework-specific and API calls can be easily implemented everywhere, we have seen no need for a shared library or similar solution so far.

TDT [7]: What are the best practices for structuring content in Drupal to take full advantage of Lupus Decoupled’s component-based approach? Are there any specific pitfalls developers should avoid?

Wolfgang Ziegler: As normal, content can and should be structured to suit the project. When configuring the custom element API,  it's advisable to limit the use of slots. While slots offer a convenient method to pass  Drupal HTML to the frontend (for example, rendering the body field), its usually better to let the frontend retain rendering control. This ensures the frontend can decide which components to use or how to customize them.

TDT [8]: How does Lupus Decoupled handle real-time updates and dynamic content changes? Is there built-in support for WebSockets or other real-time data strategies?

Wolfgang Ziegler: At the moment, Lupus Decoupled does not provide a specific solution for this. Nuxt comes with built-in support for a WebSocket server. There are plans to leverage this for real-time updates after loading the initial page, though.

TDT [9]: For large-scale enterprise applications, what are the scalability considerations when using Lupus Decoupled? Are there any specific optimizations or hosting strategies recommended?

Wolfgang Ziegler: Generally, we suggest using server rendering in the frontend, e.g., by running a containerized Node server. While we’ve seen a single container handle an impressive high load, it’s also easy to scale horizontally since there is no state involved. Paired with a regular, well-cached enterprise-Drupal stack in the backend, this scales very well.

Also, it's often a good idea to extend the solution with a search server like OpenSearch, which can be queried directly by the frontend, so there is less load on the backend. Nuxt makes it really easy to set up slim API proxies for that.

TDT [10]: Can you share insights into how custom elements work within Lupus Decoupled? How do developers extend or create their own elements for more complex layouts and interactions?

Wolfgang Ziegler: In Lupus Decoupled, custom elements are used as a concept, representing a component that the frontend renders. When configuring the API output, you typically configure your own custom elements, such as node-article-full for rendering the full article page. That maps 1:1 to a Vue or React component, but there is no requirement to expose these components using the browser custom elements API or web components. Thus, the browser custom elements API is not something the solution builds upon, although it would be possible to build up a frontend with web components instead of using Vue or React.

TDT [11]: For teams migrating an existing Drupal site to Lupus Decoupled, what are the biggest technical challenges they should anticipate, and what steps can ease the transition?

Wolfgang Ziegler: While the data model stays as it is, one needs to go over the display-related configuration, like Views and Entity-Displays. Move as much as possible to entity-displays, as they provide easily configurable output. With a well-structured  API output in place, the frontend can easily process the data.

The header and footer regions are typically placed in a fixed site layout in the frontend, which fetches the necessary menu data via a dedicated API.  This approach generally works straightforwardly and often helps to simplify things. However, special block regions or layouts can be more challenging. Although both are supported, individual blocks do not render into a clean API output out of the box, usually requiring additional work to make a block render properly into a custom element for the API. Instead of taking this approach, it’s a good idea to move more control into the frontend when possible. For example, instead of using the layout builder to configure the layout of a content type, it’s simpler to pass the necessary data for the page in the API and to build up the layout in a component in the frontend instead.

TDT [12]: What does the roadmap look like for Lupus Decoupled? Are there any upcoming features or improvements that the community can look forward to?

Wolfgang Ziegler: At the moment, we are working on integration with Drupal CMS, such that you can run Drupal CMS easily with a decoupled Nuxt frontend. For that, we’ve started looking into recipes that extend Drupal CMS with additional configurations needed for a nice API output and some suitable starter components on the frontend.

Next, we started working on a first-class support for Experience builder, the upcoming page-building solution of Drupal CMS, such that it is possible to easily place and preview Vue components from Experience Builder, while server-rendering the result efficiently. Our goal is to have this ready and fully working with the release of Experience Builder.