# How it works

In short, Lupus Decoupled Drupal bridges the gap between your Drupal backend and modern frontend frameworks, giving you the flexibility to leverage
the power of Drupal while using a modern framework for rendering. It does that by providing an API for fetching page-data from Drupal, utilizing custom elements to compose pages from high-level components.

## What is a custom element?

Custom elements refer to non-standard markup elements, commonly used for components in frontend frameworks. For example:
`<flag-icon country="nl">Netherlands</flag-icon>`. Custom elements consist of:

- **Element name** - `flag-icon`
- **Attributes**: such as `country`
- **Slots**: which can contain:
  - **Nested custom elements**
  - **Markup** or **Plain text**

For example, this is how a teaser listing using two custom elements, `teaser-listing` and `article-teaser` could look like:

```html
<teaser-listing title="Latest news" icon="news">
    <article-teaser
        href="https://example.com/news/1"
        excerpt="The excerpt of the news entry."
    >
    </article-teaser>
    <article-teaser
        href="https://example.com/news/2"
        excerpt="The excerpt of another news entry."
    >
    </article-teaser>
</teaser-listing>
```

## Providing custom elements

While custom elements can be easily created in a custom Drupal route [with code](lupus-decoupled.org/drupal/custom-elements), the most common needs can be served by utilizing the Drupal UI to configure the API output. Lupus Decoupled Drupal already provides custom elements output for the main routes of all content entities and allows customizing it via UI, see [Customized API output](lupus-decoupled.org/guide/customized-api-output).

## Custom Elements Page-API

Lupus Decoupled Drupal introduces the `/ce-api/<route>` Drupal API endpoint, which takes care of rendering a regular Drupal request into a custom-elements API response. So Drupal paths like `/node/1` or `/news` would be served by the API as pages rendered with custom element at `/ce-api/node/1` and `/ce-api/news`.

This endpoint results in the following custom-elements API response, which can serialize the elements either into JSON (default) or markup. For example, the API output of a `/news` page outputting the previous example custom elements would be:

::code-group
```json [/ce-api/news]
{

    "title": "News Listing",
    "content_format": "json",
    "content": {
          "element": "teaser-listing",
          "props": {
                "title": "Latest news",
                "icon": "news"
          },
          "slots": {
                "default": [
                      {
                            "element": "article-teaser",
                            "props": {
                                  "href": "https://example.com/news/1",
                                  "excerpt": "The excerpt of the news entry."
                            }
                      },
                      {
                            "element": "article-teaser",
                            "props": {
                                  "href": "https://example.com/news/2",
                                  "excerpt": "The excerpt of another news entry."
                            }
                      }
                ]
          }
    },
    "messages": [ ],
    "breadcrumbs": [ ],
    "metatags": {
      "meta": [
        {
          "name": "title",
          "content": "Drupal powered metatags"
        }
      ],
      "link": [
        {
          "rel": "canonical",
          "href": "https://example.com/"
        }
      ]
    }
}
```

```json [/ce-api/news?_content_format=markup]
{
    "title": "News Listing",
    "content_format": "markup",
    "content": "
      <teaser-listing title=\"Latest news\" icon=\"news\">
        <article-teaser to=\"https://example.com/news/1\" excerpt=\"The excerpt of the news entry.\" slot=\"default\"></article-teaser>
        <article-teaser to=\"https://example.com/news/2\" excerpt=\"The excerpt of another news entry.\" slot=\"default\"></article-teaser>
      </teaser-listing>",
    "messages": [ ],
    "breadcrumbs": [ ],
    "metatags": {
      "meta": [
        {
          "name": "title",
          "content": "Drupal powered metatags"
        }
      ],
      "link": [
        {
          "rel": "canonical",
          "href": "https://example.com/"
        }
      ]
    }
}
```
::

## The frontend

The frontend typically proxies requests to the Drupal `/ce-api` endpoint, while preserving the request URI and optionally some request headers.
That way, a request to `/news` is served by the frontend, which requests the backend API at `/ce-api/news` and takes care
of rendering the response. By forwarding the cookie header, the frontend may easily leverage Drupal [authentication handling](lupus-decoupled.org/guide/authentication).

While any frontend framework or tooling may be used to render the custom elements API response, Lupus Decoupled Drupal comes with a ready-to-go [Nuxt](https://nuxt.com){rel="&#x22;nofollow&#x22;"} setup by default. This enables you to get started quickly using [Vue](https://vuejs.org){rel="&#x22;nofollow&#x22;"} [Single-File-Components](https://vuejs.org/guide/scaling-up/sfc){rel="&#x22;nofollow&#x22;"}, which implements a template and web-standard oriented approach.

## Rendering custom elements

Generally, each custom element maps to a Vue component, which is automatically picked up for rendering, when the component is named exactly like the custom element. For example, for the element `article-teaser` create the component `ArticleTeaser.vue`.

The following example shows how Vue components for the previous custom elements could look like:

::code-group
```vue [TeaserListing.vue]
<template>
  <div class="teaser-listing">
    <h2>Title: {{ title }}</h2>
    <slot />
  </div>
</template>

<script setup lang="ts">
  defineProps<{
    title: string;
  }>();
</script>
```

```vue [ArticleTeaser.vue]
<template>
  <div class="article-teaser">
    <a :href="href">{{  excerpt }}</a>
  </div>
</template>

<script setup lang="ts">
  defineProps<{
    href: string;
    excerpt: string;
  }>();
</script>

```
::

The above example of `TeaserListing.vue` makes use of native Vue slots to render the article teasers. With JSON-based rendering (the default), the Nuxt Drupal CE connector automatically handles slot content - simply use `<slot />` in your template and it works out of the box. Markup-based rendering requires additional setup and configuration. Refer to [Render custom elements](lupus-decoupled.org/nuxt/render-custom-elements) docs for more details.

## First steps

Best, test things yourself by either quickly launching a [cloud environment](lupus-decoupled.org/get-started/play-online) or setting up a [new project](lupus-decoupled.org/get-started/create-new-project) locally, then continue with your [first steps](lupus-decoupled.org/get-started/first-steps).


# Play online

## About GitHub Codespaces

[GitHub Codespaces](https://github.com/features/codespaces){rel="&#x22;nofollow&#x22;"} is a cloud-based development environment integrated with
GitHub, allowing you to develop directly within your browser. Github Codespaces
provides 120 hours and 15 GB/month storage for *free*! This allows you to explore
**Lupus Decoupled Drupal** without a local setup.

## Quick Start with Preconfigured Codespaces

Choose one of the following preconfigured development environments based on
your needs (clicking on a link launches that Codespace):

- [Drupal 11 + Nuxt Naked Starter](https://codespaces.new/drunomics/lupus-decoupled-project?quickstart=1){rel="&#x22;nofollow&#x22;"}
- [Drupal 11 + Nuxt with shadcn/ui components](https://codespaces.new/drunomics/lupus-decoupled-project?quickstart=1&devcontainer_path=.devcontainer%2Fnuxt-shadcn%2Fdevcontainer.json){rel="&#x22;nofollow&#x22;"}
- [Drupal 11 + Next.js frontend](https://codespaces.new/drunomics/lupus-decoupled-project?quickstart=1&devcontainer_path=.devcontainer%2Fnextjs%2Fdevcontainer.json){rel="&#x22;nofollow&#x22;"}

## How to Use It?

1. Click on the link for your desired configuration.
2. GitHub will automatically create a new Codespace with the selected setup.
3. Wait for the container to initialize—this may take a few minutes.
4. Once ready, the development environment is fully set up and running in your browser.
5. In the `ports`tab there are links to the running services.
   - Frontend is available by clicking the link next to port 3000.
   - Backend is at port 80. By default it redirects to frontend. To prevent redirect visit the /user/login path of backend URL.

The environment may take a few minutes to initialize. Once you are up and running, try adding some content nodes and
menu items to see it working . Then continue with your [first steps](lupus-decoupled.org/get-started/first-steps)

## What’s Included in the Setup?

- A fully configured development container, with both Drupal and a frontend.
- Automatic port forwarding for running services.
- Development setup based upon ddev.


# Create a new project

## Local setup with ddev

For setting up a new project, you may want to use the [lupus-decoupled-project](https://github.com/drunomics/lupus-decoupled-project/){rel="&#x22;nofollow&#x22;"} template, which supports both [cloud environments](lupus-decoupled.org/get-started/play-online)
and local docker-based development environments via [DDEV](https://docs.ddev.com){rel="&#x22;nofollow&#x22;"}.

### Prerequisites: ddev & docker

ddev is a ridiculously simple setup for complex development environments, based upon docker compose.

Requirements:

- ddev v1.23 or later. Please follow the [installation instructions](https://ddev.readthedocs.io/en/latest/users/install/ddev-installation/){rel="&#x22;nofollow&#x22;"}

### Launch it

To spin up the project locally run:

```bash
git clone git@github.com:drunomics/lupus-decoupled-project.git
cd lupus-decoupled-project
ddev start
ddev composer install
ddev drush site-install -y --account-pass=admin --site-name='lupus_decoupled' standard
ddev drush pm-enable lupus_decoupled, services_env_parameter -y
# Configure lupus-decoupled frontend base URL
ddev drush config:set lupus_decoupled_ce_api.settings frontend_base_url https://lupus-nuxt.ddev.site -y
# Login and get started adding some test-nodes
ddev drush user-login
```

When using ddev locally, the URLs are by default:

- Frontend: <https://lupus-nuxt.ddev.site>{rel="&#x22;nofollow&#x22;"}
- Backend: <https://lupus-decoupled.ddev.site/admin>{rel="&#x22;nofollow&#x22;"}

Once you are up and running, try adding some content nodes and menu items to see it working and continue with your [first steps](lupus-decoupled.org/get-started/first-steps)

### ddev configuration

#### URLs

If you want to customize URLs, take a look at the [.ddev/config.yaml](https://github.com/drunomics/lupus-decoupled-project/blob/main/.ddev/config.yaml){rel="&#x22;nofollow&#x22;"} file and re-run `ddev start`.

#### Frontend repository

By default, the naked [nuxt-starter](https://github.com/drunomics/lupus-decoupled-nuxt-starter){rel="&#x22;nofollow&#x22;"} frontend repository is used. It can be customized by setting the `FRONTEND_REPOSITORY` via ddev config:

```bash
# Configure a different frontend repository.
ddev config --web-environment-add="FRONTEND_REPOSITORY=https://github.com/drunomics/lupus-decoupled-nuxt-shadcn"
```

### Resources

- [.ddev/config.yaml](https://github.com/drunomics/lupus-decoupled-project/blob/main/.ddev/config.yaml){rel="&#x22;nofollow&#x22;"} - main ddev (default) configuration, can be generated by running `ddev config`
- [ddev docs](https://ddev.readthedocs.io){rel="&#x22;nofollow&#x22;"}

## Custom setup

If preferred, you can incorporate the pieces in your custom setup and/or setup everything from scratch by following the next steps.

### Setting up Drupal

If you don't have an existing Drupal installation yet, or you want to start from scratch,
install Drupal first:

```bash
composer create-project drupal/recommended-project drupal-project
cd drupal-project
```

If you do not have composer installed, see the official [composer installation instructions](https://getcomposer.org/download/){rel="&#x22;nofollow&#x22;"}.

Continue with the Drupal installation, e.g. by using Drupal's quick start command:

```bash
php ./web/core/scripts/drupal quick-start standard
```

The quick-start command uses PHP's built-in webserver to run your site. Just keep it running after installation.

If you prefer a full local development setup based upon docker, check the
[Local development guide](https://www.drupal.org/docs/official_docs/local-development-guide){rel="&#x22;nofollow&#x22;"}.

Add [drush](https://drush.org){rel="&#x22;nofollow&#x22;"} - the Drupal cli:

```bash
composer require drush/drush
# If no global drush launcher is already in use, run
alias drush=$PWD/vendor/bin/drush
```

### Adding Lupus Decoupled Drupal

The [Lupus Custom Elements renderer module](https://www.drupal.org/project/lupus_ce_renderer){rel="&#x22;nofollow&#x22;"} lets Drupal provide
an API backend rendering custom elements. Add the module and its dependencies, then enable the module
via the UI or if installed, via [drush](https://drush.org){rel="&#x22;nofollow&#x22;"}.

```bash
composer require drupal/lupus_decoupled
drush en lupus_decoupled -y
drush user-login
```

Test your installation by opening `http://127.0.0.1:8888/ce-api/` - when logged in,
you should see a JSON response with the following `content` property:

```html
<drupal-markup>Welcome to your custom-elements enabled Drupal site!</drupal-markup>
```

### Setting up Nuxt

::code-group
```bash [npx]
npx nuxi@latest init <project-name>
```

```bash [pnpm]
pnpm dlx nuxi@latest init <project-name>
```
::

Answer the questions as preferred, generally the defaults work fine.
Once the project is created, you can remove the example components.

For further details, please refer to the [official Nuxt installation docs](https://nuxt.com/docs/getting-started/installation){rel="&#x22;nofollow&#x22;"}.

### Adding the Nuxt connector module

Please refer to the [Setup steps](lupus-decoupled.org/nuxt/setup) then continue below.

### Run nuxt

Ready to go! Start testing by running Nuxt in development mode:

::code-group
```bash [npm]
npm run dev
```

```bash [yarn]
yarn dev
```

```bash [pnpm]
pnpm dev
```
::

Now, when accessing the nuxt dev server (e.g. at <http://localhost:3000/>{rel="&#x22;nofollow&#x22;"})
you should see a naked page rendered, having the "Home" breadcrumb
and the message shown to logged-out users on the frontpage:
"You are not authorized to access this page."

### Connecting the dots

In your Drupal backend, set the URL of your frontend site, either via UI or via console:

```bash
drush config:set lupus_decoupled_ce_api.settings frontend_base_url http://localhost:3000 -y
```


# First steps

This page provides a short playbook which introduces you to the most important features of Lupus Decoupled Drupal. It only takes 1-2 minutes to follow:

## Creating and viewing content

1. Create an article
   In the backend, login and go to `/node/add/article` to create some first example content. Fill in some random content and save it.
2. After saving, you are redirected to the frontend, which renders the basic data of your content. You can customize that easily, as described under the [Customized API output](lupus-decoupled.org/guide/customized-api-output) page. For now, stay here and remember the frontend URL of your page, e.g. `/node/1`.
3. On the frontend go the user login, e.g. `/user/login?destination=/`. Login with your usual Drupal credentials, e.g. as admin or editor account. For the Gitpod demo environments you can log in with `admin` and password `lupus123`.
4. After logging in, go back to your created content in the frontend, e.g. `/node/1`. Take note of the local task links (or "Drupal-tabs") that appear now.
5. Click the `Edit` task link, to get back to the Drupal edit page. Now, let's change the *URL-alias* of the content in the right sidebar, e.g. to `/example-path`. Also, in the sidebar, enable the option to provide a menu item and keep the defaults.
6. Save the form and take note of the changes appearing in the frontend:
   - The URL of the content changed to `/example-path`.
   - A menu items is appearing in the main menu, which is part of the site header.
   - A success message is provided by Drupal and shown in the frontend.
7. Optionally, you may log out in the frontend, separate from the backend, by visiting the `/user/logout` path in the frontend.

## Inspecting API output of content

1. After creating content, it's listed in Drupal's content management screen at `/admin/content/node` in the backend.
2. To inspect the custom element API output of some content, use the drop-down next to the `Edit` operation button on the right and choose the entry `API output`. It shows the API output of the associated page.
3. Optionally, switch between markup and JSON serialization by appending the query parameter `?_content_format=markup` or `?_content_format=json` (default) to the URL of the API output.
4. Continue with [customizing the API output](lupus-decoupled.org/guide/customized-api-output).


# Customized API Output

Lupus Decoupled Drupal provides custom elements output for all content entities. This includes the page of a content node ("Full content"), just as the individual view-modes that may be used in content listings, e.g. teasers (Drupal allows the configuration of any number of view-modes).

A content entity can be rendered into custom elements via three methods, while the method used can be configured by view-mode. For example, when editing a content type at `admin/structure/types` go to the tab "Manage custom element" to configure your method.

**Note**: This requires the Custom Elements UI submodule, make sure it is enabled.

The three methods are:

- Custom Element Display Configuration - The typically used default method. It allows fine-grained control of the output via UI. Please see below for more details.
- Layout builder - When enabling the "Layout Builder" module for a view-mode, the layout builder may be used to allow editors to compose pages that are displayed using custom elements. Refer to the [Layout Builder guide](lupus-decoupled.org/guide/layout-builder) for details. Activate it by ticking the "Use Layout Builder" checkbox in the UI; this checkbox is visible only after a layout is enabled through "Manage display".
- Automatic processing (advanced) - A method that allows taking full control of the output via PHP code, as outlined [here](lupus-decoupled.org/drupal/custom-element-processors). Activate it by ticking the "Automatic processing" checkbox in the UI.

## Custom Element Display Configuration

For each view-mode, the display configuration may be used to configure the `name` of the custom element used. Next, for each content field the data may be mapped to a slot or property with a configurable name:

![Screenshot of custom elements UI](lupus-decoupled.org/images/ce-ui.png)

For each field various options are available:

- **Auto** - Provides a reasonable default based upon [automatic processing](lupus-decoupled.org/drupal/custom-element-processors) of the field.
- **Raw** - Provides the raw Drupal field data.
- **Flattened** - Instead of containing a nested object for individual data properties of a field, the output is flattened and each property gets added to the main element, prefixed by the property name. For example, a field with the data properties `value` and `format` would get flattened to `foo-value` and `foo-format` attributes, when the name `foo` is configured. Note that for fields containing multiple values, only the first value is output and flattened.
- **Formatted - ...**: Every Drupal field formatter rendering a field into HTML is available.
- **Custom element - Rendered entity**: This is available only for entity reference fields. It's a powerful way to configure the rendering of the referenced data. The display of the selected entity and view-mode can be configured via its own "Custom Element Display Configuration". That way the output data of referenced entities can be controlled in high detail. Furthermore, by enabling the "Flatten" option the data may be flattened into the main element.

Note that the list of available options is plugin-based, and thus extendable by Drupal modules.


# Pages & Routing

By default, the frontend forwards all page requests to Drupal. Given that, Drupal's routes, URL aliases as well as 404 or 403 pages all work out of the box. However, the frontend may add custom routes in front of Drupal's routing, see "Custom routes in the frontend".

## Configure error page and frontpage

The default pages (front, 403, and 404) are configured in the Drupal admin UI under:

**Administration** > **Configuration** > **System** > **Site information**

## URL Aliases

URL aliases are configured in the Drupal admin UI and just work. Configure them at:

**Administration** > **Configuration** > **Search and metadata** > **URL aliases**

## Custom routes in the frontend

The frontend can also define custom routes. When the frontend defines a custom route, it takes priority and works as usual. When no custom route is defined, the frontend default route forwards requests to Drupal and Drupal's routing takes effect.

For more information on defining custom routes with nuxt, please see the [Custom routes](lupus-decoupled.org/nuxt/custom-routes) section.


# Site layout & Menus

## Site layout

By default, Lupus Decoupled Drupal only serves the main page content as part of its page API response. That way, the overall site layout may be custom-built in the frontend, while some dynamic elements like navigation menus are fetched from Drupal using separate API requests.

![Diagram of site layout](lupus-decoupled.org/images/site-layout.webp)

Thanks to client-side navigation, the header and footer does not need to be re-fetched for subsequent pages.

That means, by default, the Drupal "Block layout" configuration is ignored and not applied. By installing the "Lupus Decoupled Drupal - Blocks" submodule, support for that configuration may be enabled. Please refer to [Advanced Topics > Block layout](lupus-decoupled.org/advanced-topics/block-layout) for more details on that.

Finally, it's possible to swap the used site-layout for some pages, e.g. by changing the value of the "layout" attribute for the page API responses. Please refer to [Nuxt > Page Layouts](lupus-decoupled.org/nuxt/page-layouts) for more details on that.

## Navigation menus

Lupus Decoupled Drupal integrates with the [Rest menu items](https://drupal.org/project/rest_menu_items){rel="&#x22;nofollow&#x22;"} module.
That module is automatically installed and configured as part of Lupus Decoupled Drupal, so the REST API endpoints providing the Drupal menu items (see /admin/structure/menu) are available under [https://yourdrupalsite.com/ce-api/api/menu\_items/{menu\_name}](https://yourdrupalsite.com/ce-api/api/menu_items/%7Bmenu_name%7D){rel="&#x22;nofollow&#x22;"}.

Combined with the default menu components provided by the Nuxt Drupal CE Connector modules, the main menu works out of the box, while additional menus may be fetched and displayed the same way.


# Authentication

Since page requests are processed by Drupal as usual, Drupal's authentication and session handling
stays fully working. Thus, when requests provide an authentication cookie, authentication just works. By default, cookie-based authentication with a separate frontend cookie is used.

## Cookie-based authentication

Cookie-based authentication can be achieved in one of the following three ways:

### 1. Separate frontend cookie

This is the default configured of the provided project template. The Nuxt Drupal CE Connector module forwards the cookie of every request. Thus, when a user logs in on the frontend domain, the set-cookie header is also forwarded and a cookie gets set on the frontend domain and thus is applied automatically.

The login on the frontend works via the regular Drupal login form when the "Lupus Decoupled User Form" is enabled. Simply visit `/user/login?destination=/` on the frontend to access it.

That way, the frontend login works with the same user accounts as the backend, but uses a separate session. The frontend and the backend needs a separate login. Also, since this variant requires a server, it only works in a server-rendered frontend setup.

### 2. Shared cookie domain

The Nuxt Drupal CE Connector module makes sure to forward a received cookie to the backend, such that authenticated requests just work. Instead of having a separate frontend cookie, Drupal may be configured to set the cookie on a shared, parent cookie domain. For example `drupal.example.com` and `nuxt.example.com` can both use the cookie on `.example.com`.

The Drupal cookie domain is configured via its `services.yml` file. Besides that, the project template supports setting the cookie domain via an environment variable, please refer to its [README](https://github.com/drunomics/lupus-decoupled-project?tab=readme-ov-file#automatic-frontend-login-via-a-shared-cookie-domain){rel="&#x22;nofollow&#x22;"} for further details.

### 3. CORS setup

When the JavaScript application sends requests directly to Drupal, it's possible to leverage cookie-based authentication when configuring CORS appropriately. Lupus Decoupled Drupal comes with a CORS submodule which takes care of the necessary setup. However, browser privacy features may intervene and not send the cookie to another domain reliably in some cases.

## OAuth / OpenID Connect

Drupal provides great support for OAuth based login flows via the [Simple OAuth](https://www.drupal.org/project/simple_oauth){rel="&#x22;nofollow&#x22;"} extension module. A frontend may use it to authenticate all or some requests with it. For example, it might be useful for authenticating requests to a protected API that is called from the frontend server.


# Metatags & Local tasks

Lupus Decoupled Drupal integrates with the Drupal Metatags module and local tasks (Drupal tabs) and provides them as part of the API response.

The [Nuxt CE connector](https://github.com/drunomics/nuxtjs-drupal-ce){rel="&#x22;nofollow&#x22;"} has that functionality built-in, such that metatags, link relations and local tasks work out of the box.

## Metatags

The frontend can access the metatags via the `metatags` property of the API response.

The metatags are grouped by their group name, e.g. `meta` or `jsonld`. Each group contains an array of metatags.

Example API output:

```json
"metatags": {
  "meta": [
    {
      "name": "title",
      "content": "Lupus Decoupled Drupal"
    },
    {
      "name": "description",
      "content": "Lupus Decoupled Drupal"
    },
    {
      "property": "og:url",
      "content": "https://lupus-decoupled.org"
    },
  ],
  "link": [
    {
      "rel": "canonical",
      "href": "https://lupus-decoupled.org"
    }
  ]
},
```

The metatags can be configured by visiting:

**Administration** > **Configuration** > **Search and metadata** > **Metatag**

## Schema.org via JSON-LD

The [Schema.org](https://schema.org/){rel="&#x22;nofollow&#x22;"} structured data markup is supported via the Drupal extension module [Schema Metatag](https://www.drupal.org/project/schema_metatag){rel="&#x22;nofollow&#x22;"}. When installed, the structured data can be configured through the Metatag module's user interface. The data is output in the API response under the `jsonld` metatag group. On the frontend, the Nuxt Drupal-CE connector supports outputting JSON-LD and handles it automatically.

## Local tasks

The frontend can access the local tasks via the `local_tasks` property of the API response.

The local tasks are grouped by their primary and secondary tabs.

Example API output:

```json
"local_tasks": {
  "primary": [
    {
      "url": "/frontpage",
      "label": "View",
      "active": true
    },
    {
      "url": "/node/1/edit",
      "label": "Edit",
      "active": false
    },
    {
      "url": "/node/1/delete",
      "label": "Delete",
      "active": false
    },
    {
      "url": "/node/1/layout",
      "label": "Layout",
      "active": false
    },
    {
      "url": "/node/1/revisions",
      "label": "Revisions",
      "active": false
    },
    {
      "url": "/entity_clone/node/11",
      "label": "Clone",
      "active": false
    },
  ],
  "secondary": []
}
```


# Breadcrumbs & Messages

## Breadcrumbs

The Lupus custom elements renderer module integrates with Drupal's breadcrumb handling and simply provides the breadcrumbs generated by Drupal as part of its API response.
Combined with the default components provided by the Nuxt Drupal CE Connector module, the breadcrumbs are output as generated by default.

Drupal breadcrumbs may be customized using Drupal's API or by installing some contributed
module that provide UI for doing so, for example [Easy breadcrumb](https://www.drupal.org/project/easy_breadcrumb){rel="&#x22;nofollow&#x22;"}.

## Messages

The Lupus custom elements renderer module integrates with Drupal's message handling
and simply provides Drupal messages as part of its API response. Combined with the
default components provided by the Nuxt Drupal CE Connector modules, Drupal messages are displayed automatically.

### Messages with static site generation

When a redirect points to a statically pre-generated page, there is no API request made for the static page. For a message to be displayed, the message must be sent with the redirect response (unlike with the next page response, which is the Drupal default).

### Messages with server renderings

For server-rendering, messages need to be sent with the subsequent page response. If sent with the redirect response, a message is only displayed when the redirect response is handled by a client-side API request. To fix this for server-rendered redirect responses, please see [this issue](https://www.drupal.org/project/lupus_ce_renderer/issues/3467399){rel="&#x22;nofollow&#x22;"}.


# Redirects

Lupus Decoupled Drupal supports CMS-controlled redirects, i.e. Drupal's page API explicitly informs the frontend
about redirects to be generated. The frontend, in turn, simply generates the right redirect responses. That way,
Drupal-managed redirects just work in the decoupled frontend.

## Redirect API responses

The Drupal [page API](lupus-decoupled.org/get-started/how-it-works#custom-elements-page-api) may return data about the page to render OR alternatively
a redirect response. A redirect response is formatted like this:

```json [/some-redirected-path]
{
      "redirect": {
            "external": false,
            "url": "/new-path",
            "statusCode": 301
      },
      "messages": [ ]
}
```

In the above example, the frontend would return a HTTP 301 redirect to `/new-path` when the path `/some-redirect-path`
is requested.

## Managing redirects via UI

The Drupal [Redirect module](https://www.drupal.org/project/redirect){rel="&#x22;nofollow&#x22;"} provides the ability to create manual redirects and maintains a canonical URL for all content, redirecting all other requests to that path. To use the module with Lupus Decoupled Drupal, simply install and use it - it just works.

## Creating redirects via code

Drupal modules may programmatically create redirect responses. To do so, simply return a regular redirect response
object from the route, the Lupus CE Renderer module is taking care of converting it to a redirect JSON
response when the custom-elements format is requested automatically.


# Editorial previews

## Content previews

When editing a content node, Drupal displays a preview button. The Lupus custom elements renderer module supports rendering preview routes, so previews of content nodes work fine. For improving this preview with a back button, please refer to [this issue](https://www.drupal.org/project/lupus_ce_renderer/issues/3347003){rel="&#x22;nofollow&#x22;"}.

## Responsive preview

Lupus Decoupled Drupal integrates with the Drupal [responsive preview module](https://www.drupal.org/project/responsive_preview){rel="&#x22;nofollow&#x22;"}. After installing the extension module, simply enable the provided "Lupus Decoupled Responsive Preview" module.

When the module is setup, the responsive preview widget in the Drupal admin toolbar may be used on the content node edit form to open the preview in a modal dialog.


# Layout builder

::note
**Consider using [Drupal Canvas](lupus-decoupled.org/guide/canvas) instead.**

 Canvas is Drupal's modern page builder and supersedes Layout Builder for most decoupled use cases. Layout Builder remains supported but Canvas is recommended for new projects.
::

The Drupal [layout builder](https://www.drupal.org/docs/8/core/modules/layout-builder){rel="&#x22;nofollow&#x22;"} module may be leveraged for customizing the page layout per entity or content type within Drupal. Optionally, this default may be customized by each individual content item. That way, the module can be used as a custom page builder tool.

## Rendering layouts

By default, layouts are rendered using a `<drupal-layout>` custom element for each layout section, such that any section settings are forwarded to the frontend. Contained blocks may build their content using custom elements, or fallback to Drupal rendering and regular HTML.

Please see [Drupal > Providing blocks](lupus-decoupled.org/drupal/providing-blocks) for more details on how to provide Drupal blocks that render custom elements.

## Layout previews

Lupus Decoupled Drupal provides a route for previewing layouts in the frontend, i.e. `node/XX/layout-preview`. For providing a nice UX to open the preview, the integration with the responsive preview module is leveraged (see [editorial previews](lupus-decoupled.org/guide/editorial-previews)). The responsive preview widget in the Drupal admin toolbar may be used on the layout builder page to open the preview in a modal dialog. Additionally, a link to open a full-page preview in a new tab is provided.


# Decoupling Drupal Canvas

[Drupal Canvas](https://www.drupal.org/project/canvas){rel="&#x22;nofollow&#x22;"} is Drupal's modern page builder ([docs](https://project.pages.drupalcode.org/canvas/){rel="&#x22;nofollow&#x22;"}). When paired with Lupus Decoupled, Canvas becomes a powerful decoupled page builder that supports varying frontend frameworks.

## How It Works

Canvas pages are built from components in Drupal's Canvas editor. In this context, a component can be a custom element (a Vue/React component provided by the frontend) or a regular Drupal block — which can render any Drupal content, including Views blocks that themselves output custom elements. While editing, the editor renders live previews of components via JavaScript using a preview provider (i.e. the frontend). Once published, the page is served through the CE API like any other content (e.g. `/ce-api/page/{id}`), as regular [custom elements API](lupus-decoupled.org/drupal/custom-elements) output, so components are regularly rendered by the frontend.

## Drupal CMS

When using [Lupus Decoupled Starter](lupus-decoupled.org/advanced-topics/site-templates) or a similar site template based upon Lupus Decoupled, you get a fully working setup with Canvas pre-configured. Refer to the [Drupal CMS page](lupus-decoupled.org/guide/drupal-cms) for details.

## Manual Setup

Apply the [Lupus Decoupled Canvas Recipe](https://www.drupal.org/project/lupus_decoupled_recipe_canvas){rel="&#x22;nofollow&#x22;"} to set up the module and its dependencies with a single recipe apply:

```bash
composer require drupal/lupus_decoupled_recipe_canvas
drush recipe ../recipes/lupus_decoupled_recipe_canvas
```

This installs and configures [Canvas](https://www.drupal.org/project/canvas){rel="&#x22;nofollow&#x22;"}, [Canvas ExtJS](https://www.drupal.org/project/canvas_extjs){rel="&#x22;nofollow&#x22;"}, and the Lupus Decoupled Canvas sub-module.

### Configuring the Editor Theme

Configure the theme used for Canvas editor previews at `/admin/config/system/lupus-decoupled/settings` under "Lupus Decoupled theme". A minimal theme like Stark or [Lupus Stark](https://www.drupal.org/project/lupus_stark){rel="&#x22;nofollow&#x22;"} is recommended.

## Providing Components

Components are provided via a **component index**: a JSON file listing available components, their props, and metadata. [Canvas External JS Components](https://www.drupal.org/project/canvas_extjs){rel="&#x22;nofollow&#x22;"} (a Canvas extension for integrating external JavaScript components) reads this index and makes the components available in the Canvas editor UI.

- [Vue/Nuxt](lupus-decoupled.org/nuxt/canvas-components): very well supported via [nuxt-component-preview](https://github.com/drunomics/nuxt-component-preview){rel="&#x22;nofollow&#x22;"}, see [Component Index](lupus-decoupled.org/nuxt/canvas-components) and [Component Previews](lupus-decoupled.org/nuxt/component-previews)
- React: no ready-made setup yet. [fullfatthings/drupal-canvas-react](https://github.com/fullfatthings/drupal-canvas-react){rel="&#x22;nofollow&#x22;"} provides a library for exposing React components and generating a component index, but some integration work is required to wire everything together.

For documentation on how to integrate other frontend frameworks, see [Multi-Frontend](lupus-decoupled.org/advanced-topics/multi-frontend#canvas-support).

## Component Registration

### Automatic Registration via Lupus CSR Themes

When a Lupus CSR-based theme is installed, components are automatically registered from the theme's bundled component-index. No manual steps are needed.

Automatic registration also works with a decoupled frontend when the `lupus_decoupled_canvas` module is installed, provided the configured frontend exposes a component index at the configured frontend base URL.

### Decoupled Frontends

When using a decoupled frontend (e.g. a dev server), component registration must be triggered manually:

- **UI**: Go to **Administration > Appearance > Components > External JS** (`/admin/appearance/component/extjs`)
- **Drush**: `drush canvas:extjs-auto-register`
- **Recipe config action**: Use `lupus_decoupled_canvas:registerComponents` after configuring the preview provider URL

When the frontend base URL is changed via the Lupus Decoupled settings form, a prompt will remind you to update the component registration.

## Relationship to Canvas Code Components

Drupal Canvas has built-in support for (P)React "code components" with their own bundler. These components are purely client-side rendered and currently do not integrate with Lupus Decoupled's CE API pipeline. Adding support for embedding them as custom elements would be straightforward, but is not implemented yet.


# Drupal CMS with Lupus Decoupled

[Drupal CMS](https://www.drupal.org/project/cms){rel="&#x22;nofollow&#x22;"} is Drupal's user-friendly distribution aimed at marketers and content teams. Lupus Decoupled supports it via site templates, providing a fully decoupled setup out of the box.

The [Lupus Decoupled Starter](https://git.drupalcode.org/project/lupus_decoupled_starter){rel="&#x22;nofollow&#x22;"} is a ready-to-use Drupal CMS site template that bundles:

- **Drupal CMS base setup**: content types, editorial workflow, and other Drupal CMS defaults
- **Lupus Decoupled Recipe**: core modules and configuration
- **Lupus Decoupled Canvas**: Canvas visual editor integration
- **Lupus CSR**: client-side rendering theme with the [Nuxt Starter](https://github.com/drunomics/lupus-decoupled-nuxt-starter){rel="&#x22;nofollow&#x22;"} (set as default)

## Installation

Install the starter as a site template when setting up Drupal CMS, or apply it manually:

```bash
composer require drupal/lupus_decoupled_starter
drush site-install ../recipes/lupus_decoupled_starter
```

For a full local setup with DDEV:

```bash
mkdir my-drupal-site && cd my-drupal-site
ddev config --project-type=drupal11 --docroot=web
ddev composer create-project drupal/cms
ddev composer require drupal/lupus_decoupled_starter
drush site-install ../recipes/lupus_decoupled_starter
ddev launch
```

## First Steps

After installation, navigate to **Content > Pages** in the Drupal admin to find the provided demo content. Open a page, review it, and try editing it with the Canvas visual page builder to get familiar with the setup.

## Client-Side Rendering (CSR)

The starter uses [Lupus CSR](https://www.drupal.org/project/lupus_csr){rel="&#x22;nofollow&#x22;"} (Client-Side Rendering) as the default theme. This means:

- The frontend is pre-built and served directly from Drupal, with no separate frontend server needed
- The frontend JavaScript runs in the browser and fetches content from the CE API at `/ce-api/...` on the same origin, so no CORS configuration is required
- This is ideal for getting started quickly, but **not recommended for SEO-critical production sites** (use SSR instead)

All Lupus Decoupled documentation applies regardless of whether you use CSR or SSR. For Nuxt rendering mode details, see [Rendering modes](lupus-decoupled.org/nuxt/rendering-modes).

## Customizing the Theme

To customize the frontend, run a local frontend dev server and point Drupal to it during development:

- Go to **Configuration → Lupus Decoupled Settings** (`/admin/config/services/lupus-decoupled`)
- Set **Frontend base URL** to your dev server and enable frontend redirects

Pages and Canvas previews now render via the dev server. When adding new Canvas components or changing their props, go to **Administration > Appearance > Components > External JS** (`/admin/appearance/component/extjs`) and press **Update components**.

### Provide an Updated Lupus CSR Theme

Once customization is done, generate a production build of your frontend and configure Lupus CSR to serve it via `/admin/appearance/settings/lupus_csr`. For sub-theme packaging, see [Creating a Sub-Theme](lupus-decoupled.org/drupal/themes#creating-a-sub-theme).

For detailed instructions for the Nuxt-based default theme, see [CUSTOMIZING.md](https://git.drupalcode.org/project/lupus_csr/-/blob/1.x/examples/nuxt-starter/CUSTOMIZING.md?ref_type=heads){rel="&#x22;nofollow&#x22;"}.

## Switching to Server-Side Rendering

To move from CSR to SSR:

1. Set up a separate frontend server
2. Configure the Lupus Decoupled frontend URL to point to your frontend server and enable the frontend redirect

Refer to [Deployment strategies](lupus-decoupled.org/deployment/deployment-strategy) for options.

## Creating New Site Templates

The Lupus Decoupled Starter is designed to serve as a template for building new Drupal CMS site templates. See the [Site Templates](lupus-decoupled.org/advanced-topics/site-templates) page for guidance.


# Multi-frontend

Thanks to the component-oriented decoupling of Lupus Decoupled Drupal, it's really easy to connect a frontend of choice!

## Supported frontend frameworks

Lupus Decoupled provides supports for the following frontend frameworks:

| Framework                                                 | Technology                                                                                                                                           | Status                     | Description                                                                  | Link                                                                                                              |
| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | ---------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------- |
| [Nuxt](lupus-decoupled.org/nuxt/introduction)             | Vue.js, JavaScript                                                                                                                                   | Default, Stable & Complete | [Easy setup](lupus-decoupled.org/nuxt/setup) via re-usable connector module. | [Connector module](https://github.com/drunomics/nuxtjs-drupal-ce){rel="&#x22;nofollow&#x22;"}                     |
| [Next.js](https://nextjs.org){rel="&#x22;nofollow&#x22;"} | React, JavaScript                                                                                                                                    | Proof-of-concept           | Example implementation, see README for details.                              | [Example implementation](https://github.com/drunomics/lupus-decoupled-nextjs-example){rel="&#x22;nofollow&#x22;"} |
| Yours?                                                    | [Add it!](https://github.com/drunomics/lupus-decoupled-website/edit/main/content/3.advanced-topics/05.multi-frontend.md){rel="&#x22;nofollow&#x22;"} |                            |                                                                              |                                                                                                                   |

## Example frontends

- [Nuxt Naked Starter](https://github.com/drunomics/lupus-decoupled-nuxt-starter){rel="&#x22;nofollow&#x22;"}
- [Nuxt Shadcn Example](https://github.com/drunomics/lupus-decoupled-nuxt-shadcn){rel="&#x22;nofollow&#x22;"}
- [Next.js Example](https://github.com/drunomics/lupus-decoupled-nextjs-example){rel="&#x22;nofollow&#x22;"}
- [Nuxt 2 Example (legacy)](https://github.com/drunomics/lupus-decoupled-nuxt2-demo){rel="&#x22;nofollow&#x22;"}

## Adding a new frontend framework

Adding a support for a new framework is quite easy. Here is a short overview of what the frontend needs to take care of:

- *Proxying requests*: The frontend typically proxies requests to the Drupal `/ce-api` endpoint, while preserving the request URI and optionally some request headers.
  That way, a request to `/news` is served by the frontend, which requests the backend API at `/ce-api/news` and takes care
  of rendering the response.
- *Forwarding headers*: By forwarding the cookie header, the frontend may easily leverage Drupal [authentication handling](lupus-decoupled.org/guide/authentication).
- *Rendering page content*: The `content` section of a response contains a nested tree of custom elements that need to be rendered on the page.
- *Render a page shell*: Request [navigation menus](lupus-decoupled.org/guide/site-layout-menus#navigation-menus) and render them as part of a [site layout](lupus-decoupled.org/guide/site-layout-menus).
- *Support page attributes*: Support all page attributes provided by the Drupal [page API](lupus-decoupled.org/get-started/how-it-works#custom-elements-page-api), i.e. render [breadcrumbs and messages](lupus-decoupled.org/guide/breadcrumbs-messages), support [Metatags and Local tasks](lupus-decoupled.org/guide/metatags-local-tasks).
- *Handle errors*: Take care to not add special handling for HTTP 4xx responses, such that Drupal-controlled error pages get rendered as usual. Simply take care of forwarding the status code.
- *Handle redirects*: When the page-API generates a [redirect response](lupus-decoupled.org/guide/redirects#redirect-api-responses) instead of a page, take care to issue a suitable redirect response with the given status code instead of rendering a page.
- *Canvas support* (optional): To support [Drupal Canvas](lupus-decoupled.org/guide/canvas), two additional pieces are needed:
  - *Custom Elements preview provider*: Implement a preview provider plugin so the Canvas editor can render live component previews via an iframe. The provider receives a component name and props and renders the component in isolation. See the [Nuxt preview provider plugin](https://git.drupalcode.org/project/custom_elements/-/blob/3.x/src/Plugin/CustomElementsPreviewProvider/NuxtPreviewProvider.php?ref_type=heads){rel="&#x22;nofollow&#x22;"} as a reference implementation.
  - *Component index*: Expose a `component-index.json` endpoint listing available components, their props, and metadata. [Canvas External JS Components](https://www.drupal.org/project/canvas_extjs){rel="&#x22;nofollow&#x22;"} (a Canvas extension for integrating external JavaScript components) reads this index to populate the Canvas editor UI. See the [nuxt-component-preview component index](https://github.com/drunomics/nuxt-component-preview#component-index){rel="&#x22;nofollow&#x22;"} and [fullfatthings/drupal-canvas-react](https://github.com/fullfatthings/drupal-canvas-react){rel="&#x22;nofollow&#x22;"} for Vue and React reference implementations.

That's it!


# Listings, Views

The [Lupus Decoupled Views](https://git.drupalcode.org/project/lupus_decoupled/-/blob/1.x/modules/lupus_decoupled_views/README.md){rel="&#x22;nofollow&#x22;"}
submodule provides support for Drupal's Views module. The Views module is Drupal's native way and very powerful way of creating listings of content. It provides a UI for configuring complex queries, searches and the rendering of results, including paging.

As alternative to Views-based listings, the frontend may [create custom routes](lupus-decoupled.org/nuxt/custom-routes) and listings by querying the backend, see [JSON-API, GraphQL](lupus-decoupled.org/advanced-topics/jsonapi-graphql).

## Usage

After enabling the sub-module, create a view, skip the wizard and follow the following steps:

1. Add `Custom elements display page` to a view (not a regular page!).
2. Select `Custom elements` style as view format.
3. Select `Content` as row style. Choose the view-mode you want to use for the listed elements.
4. Configure filters and other options as needed and set a path for the view.
5. The Custom elements API of the view is available at `/ce-api/<view-path>`. Take note of the custom element name visible in the output, which will be `drupal-view-{ID}`.
6. On the frontend clone the `drupal-view--default` component and create a component using the noted custom element name `drupal-view-{ID}`. Test the view on the frontend at the configured path `<view-path>` and customize the component as desired.

Note that the chosen view-mode is automatically rendered with custom elements within the view. It's not required to force rendering it via custom elements.

## Video tutorial

In the following tutorial an example configuration can be followed: [![Video tutorial](lupus-decoupled.org/images/lupus-decoupled-youtube.png)](https://www.youtube.com/live/KKTl4z_MGSg?si=j4qWfVlo9IOiobDy&t=1352){rel="&#x22;nofollow&#x22;"}

Note: The tutorial is a year old and uses `drupal-view` as custom element name. That changed meanwhile, use `drupal-view-{ID}` as custom element name or stay with the default `drupal-view--default`.

## Status

- Support for Views is rather new and problems may arise with certain configurations. Please report any issues in the [Lupus Decoupled Drupal issue queue](https://www.drupal.org/project/issues/lupus_decoupled?categories=All){rel="&#x22;nofollow&#x22;"}.
- Atm there is no support for rendering exposed filter forms. So those need to be added manually in the frontend, when needed.
- The Row style `Fields` is not supported yet (see
  [#3461874](https://www.drupal.org/project/lupus_decoupled/issues/3461874){rel="&#x22;nofollow&#x22;"}).
- Items formatted as `Rendered entities` are supported. These are needed for [Search API Index Views](lupus-decoupled.org/searches#search-api-views).


# Searches

## Searches with Views

Basic searches based upon simple SQL-queries can be built easily with the
help of the Drupal Views module. Create a regular View and add one or more
exposed filters, for example a fulltext filter. The frontend needs to build
a custom form for the search input and send the search input data as request
query parameters to the view.

## Search API

The Drupal extension module [Search API](https://drupal.org/project/search_api){rel="&#x22;nofollow&#x22;"} constitutes a powerful framework for building searches. While out-of-the-box it comes with a database backend, there are many modules providing support for powerful Search solutions available, for example:

- [Solr](https://drupal.org/project/search_api_solr){rel="&#x22;nofollow&#x22;"}
- [Elasticsearch](https://www.drupal.org/project/elasticsearch_connector){rel="&#x22;nofollow&#x22;"}
- [OpenSearch](https://www.drupal.org/project/search_api_opensearch){rel="&#x22;nofollow&#x22;"}
- [Typesense](https://www.drupal.org/project/search_api_typesense){rel="&#x22;nofollow&#x22;"}
- [Meilisearch](https://www.drupal.org/project/search_api_meilisearch){rel="&#x22;nofollow&#x22;"}
- [Algolia](https://www.drupal.org/project/search_api_algolia){rel="&#x22;nofollow&#x22;"}

The Search API module provides configuration for the content to be indexed, including configuration for the indexed data (and its processing) on a per-field basis. The content gets indexed whenever it is changed, either instantly or delayed via Drupal's cron service (as configured). For more details, please refer to the [Search API documentation](https://www.drupal.org/docs/contributed-modules/search-api){rel="&#x22;nofollow&#x22;"}.

### Search API + Views

For building the actual Search page, again the Views module maybe be leveraged, by building a View with the Search API as query backend. Please refer to the [module documentation](https://www.drupal.org/docs/8/modules/search-api/getting-started/search-forms-and-results-pages/searching-with-views/creating-a-search-view){rel="&#x22;nofollow&#x22;"} for details on how to setup such a View. This might be a good option for simple searches.

Search index view could be configured to have a `Custom Elements Page`
display and with that configuration a custom elements search endpoint is
available. (see [Lupus Decoupled Views](lupus-decoupled.org/listings-views#status))

### Search API + Custom queries

A powerful alternative for building ambitious searches is to leverage the Search API module to index data to the search server and to have the frontend query the search server directly. That way, the frontend stays in control of the query and may make use of advanced search-server specific features in order to build a great, ambitious search experience!


# JSON-API & GraphQL

When data needs to be queried or updated from the frontend, Drupal offers plenty of options. Lupus Decoupled Drupal's provided API may be combined with any of these:

## JSON-API

Drupal core provides the JSON-API module, which is a RESTful API that works with all Drupal entities (and its access system) out-of-the-box. It comes with support for all CRUD operations, as well as custom queries. Following are the most relevant resources to get started:

- [Documentation](https://www.drupal.org/docs/core-modules-and-themes/core-modules/jsonapi-module){rel="&#x22;nofollow&#x22;"}
- [jsonapi-client npm package](https://www.npmjs.com/package/@drupal-api-client/json-api-client){rel="&#x22;nofollow&#x22;"}
- [Json\:API Extras module](https://www.drupal.org/project/jsonapi_extras){rel="&#x22;nofollow&#x22;"} - Configure which entities are exposed
- [Simple OAuth](https://www.drupal.org/project/simple_oauth){rel="&#x22;nofollow&#x22;"} - Authenticate requests via API token

## GraphQL

Alternatively, there are Drupal extension modules that add GraphQL support:

- [GraphQL module](https://www.drupal.org/project/graphql/){rel="&#x22;nofollow&#x22;"}
- [GraphQL compose](https://www.drupal.org/project/graphql_compose){rel="&#x22;nofollow&#x22;"}


# Caching

## Page-level caching

Lupus Decoupled Drupal takes advantages of Drupal's built-in caching system based around cache metadata. Given that the following modules provided by Drupal core work as usual:

- Internal Page Cache - Caches page for anonymous users, with cache-tag based invalidation.
- Dynamic Page Cache - Cache pages for authenticated users, with cache-tag based invalidation.

Since all the caching related HTTP headers get set correctly, also CDN or reverse-proxy (e.g. varnish) based caching works as usual. Just like with traditionally rendered Drupal pages, the pages rendered with custom elements have cache metadata associated, thus things like cache-tag based invalidation are supported.

Next, the following Drupal extension modules are great, optional additions and fully supported:

- [Purge module](https://drupal.org/project/purge){rel="&#x22;nofollow&#x22;"} - A general cache invalidation API, optionally with cache-tag based invalidation.
- Varnish based cache and cache-tag invalidation via [Varnish Purger](https://drupal.org/project/varnish_purge){rel="&#x22;nofollow&#x22;"}
- Modules adding further cache backends, like [Redis](https://drupal.org/project/redis){rel="&#x22;nofollow&#x22;"}
- Various CDN modules, like [Cloudflare](https://drupal.org/project/cloudflare){rel="&#x22;nofollow&#x22;"}

## Render caching

Since pages rendered into custom elements are skipping the Drupal internal, traditional render system, the Drupal-internal render-caching is bypassed. Instead of caching individual rendered pieces, whole pages can be cached well via dynamic page cache. Since the LupusCeRenderer module attaches the per-user rendered local tasks (the Drupal tabs) via a Kernel response event that is triggered after the Dynamic Page Cache, the pages can be cached efficiently across user-roles if the page-content is not user or role dependent. Additionally, the page response includes only the main content (no menus etc.), so it's often cacheable.


# Error pages

## Drupal error pages

Error pages provided by Drupal (e.g. 403, 404 page) are shown by default and can be configured in Drupal. Configuration is done in the Drupal backend under `Configuration > System > Basic site settings > Error pages`. With server-rendering, the HTTP status code is correctly forwarded.

The Nuxt error page is only shown when the backend cannot be reached (error 504 Gateway timeout).

## Custom error pages in Nuxt

In order to use regular Nuxt error pages for regular 403, 404 error pages, you can enable the `customErrorPages` option in `nuxt.config.js`:

```js
export default defineNuxtConfig({
  drupalCe: {
    customErrorPages: true,
    // options...
  }
})
```

When custom error pages are active, the nuxt error handling is used for all error HTTP status codes returned by Drupal.


# Drupal forms

::note
At the moment Drupal forms are only supported with server-side 

[rendering mode](lupus-decoupled.org/nuxt/rendering-modes)

.
::

## Overview

The "Lupus Decoupled Form" sub-module makes it easy to support Drupal forms in a decoupled frontend. The form HTML is rendered by Drupal and wrapped in a `<drupal-form>` custom element, such that the frontend can easily add some styling or custom JS-enhancements.

At the moment, progressive form submissions are supported, which work without JavaScript. JavaScript enhanced form submissions are currently not a priority, but can be achieved with some additional JavaScript code, see Issue [#3471135](https://www.drupal.org/project/lupus_decoupled/issues/3471135){rel="&#x22;nofollow&#x22;"} for some code to get started.

## How does it work?

Generally, Drupal renders the form as usual. The resulting HTML markup is wrapped into a `<drupal-form-{FORM-ID}>` component, which simply shows the server-rendered HTML of the form. When the form is submitted, the frontend takes care of forwarding the POST request to the backend, where it's processed as usual. After form processing the request is rendered in a custom element response again: Either the page response contains a reloaded form or a redirect. Any messages for form validation fails or success are handled as usual via the [Drupal message system](lupus-decoupled.org/guide/breadcrumbs-messages) and sent as part of the next page response. Thus, subsequently the frontend takes care of rendering the response appropriately in a new page or redirect response - just as it does for any other server-render page.

### Frontend support

- For the Nuxt frontend, The Nuxtjs Drupal-CE Connector module ships with a suitable default component: [drupal-form--default.vue](https://github.com/drunomics/nuxtjs-drupal-ce/blob/2.x/playground/components/global/drupal-form--default.vue){rel="&#x22;nofollow&#x22;"}
- There is [server middleware](https://github.com/drunomics/nuxtjs-drupal-ce/blob/4d8c9e43d8a3ed1f1f6480425b25016b82e57579/src/runtime/server/middleware/drupalFormHandler.ts){rel="&#x22;nofollow&#x22;"} which takes care of handling the POST request and renders the response.

## Rendering forms in the frontend

Generally, the `drupal-form--default` component may be used to add form styles and JavaScript as needed, either generally for all forms via the default component, or individually by customizing things in a per-form component `drupal-form--{FORM-ID}`.

The JavaScript libraries a form attaches - form `#states`, autocomplete, module behaviours - are emitted alongside the form markup as `<drupal-library-*>` elements, such that the frontend can load them and run the Drupal behaviours; see [Drupal JavaScript](lupus-decoupled.org/advanced-topics/drupal-javascript). Drupal CSS assets are not included, thus the frontend needs to take care of providing suitable replacement styles.

In order to change the HTML markup of forms, the form elements need to be themed in Drupal.

### Theming form elements

Since the markup is generated by Drupal, the HTML of individual form elements can be altered only by adjusting the Drupal markup with the help of a Drupal theme:

- For having a clean, semantic output of forms, the [lupus-stark theme](https://www.drupal.org/project/lupus_stark){rel="&#x22;nofollow&#x22;"} has been created - which
  adds suitable Drupal twig files to do away with unnecessary Drupal-isms. That way decent markup is
  generated and necessary style adaptions are made possible by targeting elements using the
  reasonable default classes.
- Generally, the active Drupal theme can be customized by setting the theme as site-wide standard theme. If the form is on a Drupal admin page, the Admin Theme will be applied though.
- The module adds support for a special '\_theme' key in route definitions, which allows Drupal developers to switch themes to the given theme-name specifically for the form routes, as preferred.

## Supported Drupal forms

Lupus Decoupled ships with further sub-modules that enable support for further Drupal-forms as desired:

- **Lupus Decoupled Contact Forms** - Adds support for the contact forms provided by the core contact module.
- **Lupus Decoupled User Forms** - Enables using Drupal user login and user password reset forms in the frontend. That way, user may login while getting a separate frontend cookie. Please refer to the [Authentication page](lupus-decoupled.org/guide/authentication) for details.

If you miss support for some Drupal form, please open an issue in the [Lupus Decoupled issue queue](https://www.drupal.org/project/issues/lupus_decoupled?categories=All){rel="&#x22;nofollow&#x22;"} to add it! Please refer to the page [Adding Drupal Forms](lupus-decoupled.org/drupal/add-drupal-forms) for documentation on how this is done.

## Webforms

The Lupus Decoupled Webform module provides support for [Webform](https://www.drupal.org/project/webform){rel="&#x22;nofollow&#x22;"}
module (version 6.0 or later), a popular module for building forms using the UI.

Webforms integration utilizes the Lupus Decoupled Forms
functionality (see [How it work?](lupus-decoupled.org/#how-does-it-work) section), thus
a webforms get a custom elements API endpoint.

### Limitations

The Drupal JavaScript a webform element attaches is part of the webform API
response, see [Drupal JavaScript](lupus-decoupled.org/advanced-topics/drupal-javascript) - so
conditional (`#states`) elements work as they do in Drupal. Webform elements
built on Drupal's Ajax framework or on core CSS (dialogs, off-canvas) are
not covered by that and need frontend work.

### Confirmation types

Inline and page (default) confirmations are supported, but for page
confirmation type the user (or anonymous) needs to have access to "view own
webform submissions" set on webform settings configured at
`admin/structure/webform/manage/{webform}/access`

### Submission example

A curl request example to submit a custom webform (with `test_ce_webform` id).
Note that the submission webform id is `webform_submission_test_ce_webform_add_form`.

```bash
curl -k -X POST --url https://lupus-decoupled.ddev.site/ce-api/form/test_ce_webform -F 'first_name=John' -F "last_name=Doe" -F "checkbox=1" -F "op=Submit" -F "form_build_id=form-<form-build-id>" -F "form_id=webform_submission_test_ce_webform_add_form" -H "Accept: application/json"
```


# Drupal JavaScript

## Overview

Drupal attaches JavaScript libraries to the render arrays it builds - form `#states`, autocomplete, module behaviours. In a decoupled setup only the rendered markup travels to the frontend, so those attachments would be lost on the way out. To avoid that, the [Custom Elements](https://www.drupal.org/project/custom_elements){rel="&#x22;nofollow&#x22;"} module emits every attached library as a `<drupal-library-*>` custom element next to the markup, such that a frontend can load the JavaScript and run the Drupal behaviours.

::note
Library elements are emitted by Custom Elements 3.x, in releases after 3.4.1.
::

## How does it work?

Whenever Drupal converts a render array into a custom element - a [Drupal form](lupus-decoupled.org/advanced-topics/drupal-forms), a fallback-rendered [block](lupus-decoupled.org/advanced-topics/block-layout), a [Canvas](lupus-decoupled.org/guide/canvas) component tree - the libraries that bubbled up into the render array's `#attached` are turned into custom elements:

- Library dependencies are resolved into load order by Drupal, so the frontend can load the files sequentially without knowing anything about Drupal's library graph.
- One element is emitted per library that carries JavaScript, in that order, as a sibling preceding the markup in the same slot. Libraries contributing only CSS or settings are skipped.
- The element name is the library name, lower-cased and with `/`, `.` and `_` replaced by `-`: `core/drupal.states` becomes `drupal-library-core-drupal-states`. The verbatim library name stays available in the `library` prop.
- Each element carries its library's JavaScript files in the `js` prop, as `url` (root-relative, with a cache-busting version query - or absolute for external assets) plus the `attributes` Drupal would put on the `<script>` tag.
- The merged `drupalSettings` are added to the first library element, JSON-encoded as a string so that setting keys reach the frontend verbatim.
- Stylesheets are not emitted: the decoupled frontend brings its own styles.

Example of a form response carrying two libraries:

```json
{
  "element": "drupal-form-example-form",
  "slots": {
    "default": [
      {
        "element": "drupal-library-core-drupal",
        "props": {
          "library": "core/drupal",
          "js": [{ "url": "/core/misc/drupal.js?v=11.3.13", "attributes": [] }],
          "drupalSettings": "{\"ajaxTrustedUrl\":{\"form_action_p_4kMHZg\":true}}"
        }
      },
      {
        "element": "drupal-library-core-drupal-states",
        "props": {
          "library": "core/drupal.states",
          "js": [{ "url": "/core/misc/states.js?v=11.3.13", "attributes": [] }]
        }
      },
      "<form class=\"example-form\">...</form>"
    ]
  }
}
```

## Frontend support

Library elements are ordinary custom elements, so a frontend renders them like any other element. The component doing so should:

1. Render no markup of its own - the element is a load instruction, not content.
2. Resolve the `js` URLs against the Drupal base URL, since they are root-relative.
3. Add them as `<script>` tags in the given order and keep execution order, so that dependencies run before dependents.
4. Load every URL only once per page, since libraries may share files.
5. Merge `drupalSettings` into `window.drupalSettings` before any script runs. A decoupled page has no settings `<script>` for Drupal's own `drupalSettingsLoader.js` to read, so the frontend takes that over.
6. Call `Drupal.attachBehaviors(document.body, window.drupalSettings)` once the scripts have loaded, so the behaviours attach to the server-rendered markup.
7. Skip a file that fails to load with a warning instead of aborting: some Drupal "JavaScript" is generated per request and may legitimately be unavailable in a decoupled context.

This is a client-side concern only - there is nothing to do while server-side rendering the page.

### Example: Nuxt

The Nuxt connector module ships a `loadLibrary()` composable doing all of the above, paired with a renderless default component that applies to every library element. See [Drupal JS libraries](lupus-decoupled.org/nuxt/drupal-libraries) for the Nuxt-specific documentation.

## Overriding or skipping a library

Since every library gets a custom element of its own, a frontend can take over a single library by providing a component for that element name, e.g. `drupal-library-core-drupal-states` for `core/drupal.states`. On a frontend with a default-component fallback (like [Nuxt](lupus-decoupled.org/nuxt/default-components)), that component takes precedence over the generic one, so the library's JavaScript is never loaded. That way a library can be replaced by a native frontend implementation, or skipped entirely by rendering nothing.

## Limitations

- **No CSS**: libraries whose behaviour relies on Drupal core CSS (dialog, off-canvas) work, but are unstyled until the frontend provides its own styles.
- **JavaScript-enabled behaviours only**: everything Drupal does server-side stays server-side; this only restores what Drupal would have run in the browser.
- Only `#states`-style behaviours are verified end-to-end so far. Ajax- and dialog-based libraries are expected to need more work in a decoupled context, since they rely on Drupal's own page URLs and response formats.


# Drupal CMS Site Templates

[Drupal CMS](https://www.drupal.org/project/cms){rel="&#x22;nofollow&#x22;"} supports **site templates**: pre-configured starting points that combine Drupal recipes, a theme, design elements, and default content into a fully functional website ready to use from day one. See the [Drupal blog post on site templates](https://www.drupal.org/blog/exploring-a-marketplace-for-drupal-site-templates){rel="&#x22;nofollow&#x22;"} for the broader vision.

## Lupus Decoupled Starter

The [Lupus Decoupled Starter](https://git.drupalcode.org/project/lupus_decoupled_starter){rel="&#x22;nofollow&#x22;"} is the reference site template for Lupus Decoupled. It installs:

- **Lupus Decoupled Recipe**: core decoupled modules and configuration
- **Lupus Decoupled Canvas**: Canvas visual editor integration
- **Lupus CSR**: client-side rendering theme with the [Nuxt Starter](https://github.com/drunomics/lupus-decoupled-nuxt-starter){rel="&#x22;nofollow&#x22;"} (set as default)

It is the recommended way to get started with Lupus Decoupled on Drupal CMS and serves as a template for building new site templates.

## Creating a New Site Template

To create a new Lupus Decoupled-based site template, use the Lupus Decoupled Starter as your starting point:

1. **Fork or copy** the [lupus\_decoupled\_starter](https://git.drupalcode.org/project/lupus_decoupled_starter){rel="&#x22;nofollow&#x22;"} repository. Alternatively, use `drush site:export` to export configuration from a running Drupal site and build a recipe from scratch — see [Drupal CMS Site Template Base](https://www.drupal.org/project/drupal_cms_site_template_base){rel="&#x22;nofollow&#x22;"} for the base structure to build upon.
2. **Customize the recipe**: add or remove modules, configuration, and default content to match your use case.
3. **Provide a custom CSR theme**: create a sub-theme of `lupus_csr` with your frontend build output, or configure a different frontend (see [Lupus CSR](https://www.drupal.org/project/lupus_csr){rel="&#x22;nofollow&#x22;"})

The starter's recipe structure mirrors Drupal CMS conventions, making it straightforward to adapt for industry-specific or purpose-built templates. To make your template available in the Drupal CMS marketplace, follow the [getting started guide](https://git.drupalcode.org/project/drupal_cms_site_template_base/-/blob/1.x/GET-STARTED.md?ref_type=heads){rel="&#x22;nofollow&#x22;"}.


# Block layout

As documented at [Site layout & Menus](lupus-decoupled.org/guide/site-layout-menus) by default the site header and footer are built by the frontend. That means, the Drupal *Blocks Layout* configuration is ignored for custom-elements rendered pages.

However, with the optional "Lupus Decoupled Blocks" sub-module the configured blocks may be rendered and included with the page response. This may be useful when Drupal should generate the content for a certain region for every page, e.g. a sitebar.

## How does it work

When the module "Lupus Decoupled Blocks" is enabled, all configured blocks are rendered with custom elements for every page. The result is grouped by region and added to the custom-elements page API response under a new top-level `blocks` key. In turn, the frontend just needs to render and place the custom-element content of each region on the page.


# Debugging API requests

For debugging API requests and responses, Lupus Decoupled Drupal offers
integration with [REST Log](https://www.drupal.org/project/rest_log){rel="&#x22;nofollow&#x22;"}
module.

In decoupled scenarios, visitors are making requests to the front-end application,
which is itself retrieving data from the back-end. It is helpful to see the
form of requests that reached the decoupled back-end and the responses that
the back-end provided.

Logged data consists of:

- Request method
- Request header
- Request URI
- Request cookie
- Request payload
- Response status
- Response header
- Response body
- Response time

## Usage

Make some requests either to API endpint (`/admin/content` view provides **View
API Endpoint operation** for nodes that opens their API endpoint directly) or front-end
requests and investigate them at `/admin/reports/rest_log`.

## Set up

- `composer require --dev drupal/rest_log`
- `drush en lupus_decoupled_api_log`

### Configuration

REST Log module's default configuration is sufficient but it can be changed at
`/admin/config/development/logging/rest_log`.

# Debugging with curl

Sometimes it is useful to trigger [Xdebug](https://xdebug.org/){rel="&#x22;nofollow&#x22;"} from the command
line. This can be achieved with [curl](https://curl.se/){rel="&#x22;nofollow&#x22;"}. Authorization can be
provided via session cookie with values copied from the authenticated browser
session.

Example of such curl request:

```text
curl -k -i -H 'Cookie: SSESS<session-name>=<session-cookie-value>;XDEBUG_SESSION=XDEBUG_ECLIPSE;' https://<domain>/<API-endpoint>
```


# Examples

- [Drupal Dev Days 2023 - Session Video Recordings](lupus-decoupled.org/ddd23)

Demos, showcases.


# Community

## Chat

Get in touch via the drupal Slack channel!

- Join the [Drupal slack](https://www.drupal.org/community/contributor-guide/reference-information/talk/tools/slack#s-the-main-drupal-workspace){rel="&#x22;nofollow&#x22;"}
- Join channel [#lupus-decoupled](https://drupal.slack.com/archives/C03UQBSRR0Q){rel="&#x22;nofollow&#x22;"}

## Video tutorials

There are a couple of ["ddd23" video tutorials](lupus-decoupled.org/ddd23) available, which have been recorded at the Drupal Dev Days Vienna 2023.

## Slides

- [DrupalCon Vienna - 2025-10: JavaScript frontend development with Drupal Canvas: Beyond decoupling](https://docs.google.com/presentation/d/e/2PACX-1vSt2s73uhvBcr_igQmqcMoWs4Nm8FULzkJAfn9y3nND4Dzh0PyzJBr4epjDvaKbBuki2jjJLEHJ74nc/pub?start=false&loop=false&delayms=3000){rel="&#x22;nofollow&#x22;"}
- [Drupal Developer Days Leuven - 2025-04: Nuxt for Drupal Developers - Modern frontend without the JavaScript Jungle](https://docs.google.com/presentation/d/e/2PACX-1vSQYDLOxLqIrrqe6QaHwmo7FHFFAMGpaO12nAXGL0UDdQhTzFzO63RoxNJzcbS_CPxGRaYuqSfj_gXO/pub?start=false&loop=false&delayms=3000){rel="&#x22;nofollow&#x22;"}
- [Drupal Developer Days Burgas - 2024-06: Custom Elements UI: quicker changes to
  your decoupled Drupal site](https://cp.drunomics.com/files/2024-07/2024-06-DDD-Burgas-Presentation-Custom-Elements-UI.pptx_.pdf){rel="&#x22;nofollow&#x22;"}
- [DrupalDevDays 2023 Vienna - Lupus Decoupled Drupal](https://docs.google.com/presentation/d/e/2PACX-1vSVCI3_TbuXMLUJNmw_Ls64UPziHmImvVCzROC0DNVqelNlzAakBCh4zLlGZZtIU6fAYghp8QOXmfo_/pub?start=false&loop=false&delayms=3000){rel="&#x22;nofollow&#x22;"} - Introduction by Wolfgang Ziegler // fago
- [Lupus Decoupled Drupal - Overview & Status](https://www.slideshare.net/WolfgangZiegler6/lupus-decoupled-drupal-drupal-austria-meetup-202304pdf){rel="&#x22;nofollow&#x22;"}
- [Drupalcon North America 2021 - Getting Started with the Lupus Nuxt.js Drupal Stack](https://www.slideshare.net/nuppla/getting-started-with-the-lupus-nuxtjs-drupal-stack){rel="&#x22;nofollow&#x22;"}
- [Drupal DACH Meetup - 2021-04: Decoupling Drupal with the Lupus Nuxt.js Drupal Stack](https://www.slideshare.net/nuppla/decoupling-drupal-mit-dem-lupus-nuxtjs-drupal-stack){rel="&#x22;nofollow&#x22;"}

## Session recordings

- Drupal Developer Days Leuven 2025 - Nuxt for Drupal Developers: Modern Frontend Without the JavaScript Jungle [\[Video\]](https://www.youtube.com/watch?v=tFivOmCI3yU){rel="&#x22;nofollow&#x22;"}
- DrupalDevDays 2023 Vienna - Lupus Decoupled Drupal [\[Video\]](https://www.youtube.com/watch?v=KKTl4z_MGSg){rel="&#x22;nofollow&#x22;"}
- Drupalcon NA 2021 - Getting Started with the Lupus Nuxtjs. Drupal Stack[\[Video\]](https://www.youtube.com/watch?v=dZPeBI-lMAs){rel="&#x22;nofollow&#x22;"}
- Drupalcon Europe 2020 - Custom Elements - An alternate Render API for decoupled Drupal
  [\[Video\]](https://www.youtube.com/watch?v=je6pYJ6Jzk4){rel="&#x22;nofollow&#x22;"}

## Interviews

- [A Look Under the Hood of Lupus Decoupled Drupal - The DropTimes](https://www.thedroptimes.com/interview/49234/look-under-hood-lupus-decoupled-drupal){rel="&#x22;nofollow&#x22;"}

## Blog posts

- [Lupus Decoupled Drupal brings Inertia.js-Style Development to Drupal](https://drunomics.com/en/blog/inertiajs-style-development-drupal-lupus-decoupled-drupal-221){rel="&#x22;nofollow&#x22;"}
  Explains how Lupus Decoupled enables Inertia.js-style development patterns.
- [Low-code + Decoupled Drupal: The Power of Custom Elements 3.0](https://drunomics.com/en/blog/low-code-decoupled-drupal-power-custom-elements-30-215?auth=1){rel="&#x22;nofollow&#x22;"}
  Introduces the Custom Elements UI module.
- [Custom Elements: A solution for soft-decoupled Drupal](https://drunomics.com/blog/custom-elements-our-solution-soft-decoupled-drupal){rel="&#x22;nofollow&#x22;"}
  Clarifies the goals and talks and explains the overall idea.
- [Nuxt.js - The frontend framework for decoupled Drupal with Custom Elements](https://drunomics.com/blog/nuxtjs-frontend-framework-decoupled-drupal-custom-elements){rel="&#x22;nofollow&#x22;"}
  Discusses selecting a frontend framework.
- [Lupus Decoupled Drupal: Bridging Drupal’s Backend Strength with Frontend Freedom](https://drunomics.com/en/blog/lupus-decoupled-drupal-bridging-drupals-backend-strength-frontend-freedom-207){rel="&#x22;nofollow&#x22;"}
  Gives an overview of Lupus Decoupled Drupal latest updates.
- [Why we don't use GraphQL](https://drunomics.com/en/blog/why-we-dont-use-graphql-206){rel="&#x22;nofollow&#x22;"}
  Explains GraphQL limitations and alternative solutions.


# Key modules

[Lupus Decoupled Drupal](https://www.drupal.org/project/lupus_decoupled){rel="&#x22;nofollow&#x22;"} builds upon the following two key modules:

- [Custom Elements](https://www.drupal.org/project/custom_elements){rel="&#x22;nofollow&#x22;"}
- [Lupus Custom Elements Renderer](https://www.drupal.org/project/lupus_ce_renderer){rel="&#x22;nofollow&#x22;"}

The custom elements module forms the base: It provides the API to render entities into custom elements. Based upon that the Lupus CE renderer module integrates with the Drupal routing system and renders requests of format `custom_elements` using the custom elements module. On top of that, the [Lupus Decoupled Drupal](https://www.drupal.org/project/lupus_decoupled){rel="&#x22;nofollow&#x22;"} provides the "Lupus Decoupled Custom Elements API sub-module, which makes this API available in a more opinionated way: It adds a handy `/ce-api` path-prefix and optionally handles redirection to the frontend.

## Lupus Decoupled Integration modules

[Lupus Decoupled Drupal](https://www.drupal.org/project/lupus_decoupled){rel="&#x22;nofollow&#x22;"} ships with more sub-modules that integrate modules like Views, or Forms with the stack.

## Themes

[Lupus CSR](https://www.drupal.org/project/lupus_csr){rel="&#x22;nofollow&#x22;"} is a Drupal base theme that enables serving a pre-built frontend application (e.g. a Nuxt build) directly from Drupal without a separate frontend server. It is the recommended approach for Drupal CMS site templates, demos, ready-made setups, and simple projects that do not require server-side rendering.

## Further Useful Drupal modules

Besides the main modules, the following Drupal modules are useful:

- [Rest menu items](https://drupal.org/project/rest_menu_items){rel="&#x22;nofollow&#x22;"} provides a way to easily
  fetch Drupal menus. The Nuxt Drupal module comes with built-in support for it.
- [Trusted redirect](https://www.drupal.org/project/trusted_redirect){rel="&#x22;nofollow&#x22;"} allows the frontend
  to link to Drupal while setting a `destination=<frontend_URL>` redirect target.
- [Services env parameter](https://www.drupal.org/project/services_env_parameter){rel="&#x22;nofollow&#x22;"} to
  set cookie domain or CORS configuration via environment variables. This is what the [project template](https://github.com/drunomics/lupus-decoupled-project){rel="&#x22;nofollow&#x22;"} does.


# Custom elements

## Creating custom elements

The `CustomElement` class helps modelling a tree of custom elements. The class provides an API for creating and nesting custom elements as shown the following example:

```php [Controller/News.php]
<?php
   use \Drupal\custom_elements\CustomElement;

   class NewsController extends ControllerBase {
    public function buildNewsListing() {

      $articles[] = CustomElement::create('article-teaser')
        ->setAttribute('href', 'https://example.com/news/1')
        ->setAttribute('excerpt', 'The excerpt of the news entry.');

      $articles[] = CustomElement::create('article-teaser')
        ->setAttribute('href', 'https://example.com/news/2')
        ->setAttribute('excerpt', 'The excerpt of another news entry.');

      return CustomElement::create('teaser-listing')
        ->setSlotFromNestedElements('default', $articles);
    }
  }
```

This creates:

```html
<teaser-listing title="Latest news" icon="news">
    <article-teaser
        href="https://example.com/news/1"
        excerpt="The excerpt of the news entry."
    >
    </article-teaser>
    <article-teaser
        href="https://example.com/news/2"
        excerpt="The excerpt of another news entry."
    >
    </article-teaser>
</teaser-listing>
```

### Slots

Slots are used for passing nested, arbitrary content. Slots are named and can have one or multiple child elements. The child elements keep their ordering, unless a custom weight is passed. The `default` slot is a special slot name, which is used for nested markup without a given slot-name, e.g. `<the-element>some-nested-content</the-element>`, which is the same as `<the-element><slot name="default">some-nested-content</slot></the-element>`.

### Attributes

Besides slot, an element may contain any number of attributes, which are key value pairs. Attribute values can be scalars and arrays, which - when rendered into markup format - become a JSON-encoded string.

### Cache Metadata

Custom elements integrate with Drupal's [cache API](https://www.drupal.org/docs/8/api/cache-api/cacheabledependencyinterface-friends){rel="&#x22;nofollow&#x22;"}, by allowing to define their caching dependencies via cache tags and their cache context. They implement the `CacheableDependencyInterface`, so their cache dependencies can be easily added as usual, for example entities:

```php
$custom_element->addCacheableDependency($entity);
```

When a tree of elements is rendered, cache metadata of individual elements is aggregated and bubbled up to the page, just as with Drupal's traditional render system.

### API documentation

For detailed API documentation please refer to the in-code API documentation of the `\Drupal\custom_elements\CustomElement` class.

## Rendering into custom elements

For rendering entities, and more generally any kind of data, into custom elements, the module provides the custom element generator service:

```php
    <?php
    class SomeClass {
      use CustomElementGeneratorTrait;
      public function someMethod() {
        $custom_element = $this->getCustomElementGenerator()
          ->generate($entity, $view_mode);
      }
    }
```

This will render into custom elements as configured for the entity. Refer to [Customized API output](lupus-decoupled.org/guide/customized-api-output) for an overview.

For other kind of data, for some field items, the data may be processed via "automatic processing" which makes use of [custom element processors](lupus-decoupled.org/drupal/custom-element-processors):

```php
    <?php
    class SomeClass {
      use CustomElementGeneratorTrait;
      public function someMethod() {
        $element = CustomElement::create('some-element');
        $this->getCustomElementGenerator()
          ->process($items, $element, $view_mode);
      }
    }
```

## Serializing to markup or JSON

A tree of custom elements can be output in `markup` or `JSON` format:

### Serializing to JSON

For serializing a tree of custom elements into JSON make use of the provided normalizer:

```php
    <?php
      $custom_element_normalizer = \Drupal::service('custom_elements.normalizer');
      $bubbleable_metadata = BubbleableMetadata::createFromObject($custom_element);
      $json = $custom_element_normalizer->normalize($custom_element, NULL, ['cache_metadata' => $bubbleable_metadata]);
```

### Serializing to markup

For generating markup for a tree of custom elements, simply render it via the Drupal's traditional render API:

```php
  <?php
    $render = $custom_element->toRenderArray();
    $renderer = \Drupal::service('renderer');
    $markup = $renderer->renderRoot($customElement);
  ?>
```

### Custom Element markup styles

Custom elements use "slots" for handling content distribution, i.e. for passing
nested content to an element. However, the concrete syntax used for handling
slots may differ by various frameworks. Thus, the module supports rendering to
different markup styles while it defaults to the Web component style syntax. In addition,
the module supports the [Vue2 and Vue 3](https://vuejs.org/v2/guide/components-slots.html#Named-Slots-Shorthand){rel="&#x22;nofollow&#x22;"} syntax which can be enabled via config:

```bash
drush config:set custom_elements.settings  markup_style vue-3
```

## Traditional render arrays

Custom elements may be rendered using Drupal's traditional render API:

```php
  <?php
    $render[] = $custom_element->toRenderArray();
  ?>
```

On the other hand, it's possible to wrap a traditional render array into a custom element:

```php
  <?php
    $custom_element = CustomElement::createFromRenderArray($render_array);
  ?>
```

The resulting element can be further customized, but by default it simply renders the `$render_array` and wraps it into a `<drupal-markup>` element, that the frontend may simply output.


# Routes

The Lupus CE Renderer module takes care of rendering routes of the format `custom_elements` via Drupal's regular routing system. That means a route can be defined as usual in Drupal, additionally define the `_format` to be `custom_elements`:

```php [MODULE.routing.yml]
  MODULE.listing:
      path: '/news'
      defaults:
        _title: 'News Listing'
        _controller: '\Drupal\MODULE\Controller\NewsController::buildNewsListing'
      requirements:
        _format: 'custom_elements'
        _permission: 'access content'

```

Next, the controller may simple return a custom element object:

```php [Controller/News.php]
  <?php
     class NewsController extends ControllerBase {
      public function buildNewsListing() {

        $articles[] = CustomElement::create('article-teaser')
          ->setAttribute('href', 'https://example.com/news/1')
          ->setAttribute('excerpt', 'The excerpt of the news entry.');

        $articles[] = CustomElement::create('article-teaser')
          ->setAttribute('href', 'https://example.com/news/2')
          ->setAttribute('excerpt', 'The excerpt of another news entry.');

        return CustomElement::create('teaser-listing')
          ->setSlotFromNestedElements('default', $articles);
      }
     }
```

The Lupus CE renderer module is taking care of rendering the element into either markup or JSON serialization:

::code-group
```json [/ce-api/news]
{

    "title": "News Listing",
    "content_format": "json",
    "content": {
          "element": "teaser-listing",
          "props": {
                "title": "Latest news",
                "icon": "news"
          },
          "slots": {
                "default": [
                      {
                            "element": "article-teaser",
                            "props": {
                                  "href": "https://example.com/news/1",
                                  "excerpt": "The excerpt of the news entry."
                            }
                      },
                      {
                            "element": "article-teaser",
                            "props": {
                                  "href": "https://example.com/news/2",
                                  "excerpt": "The excerpt of another news entry."
                            }
                      }
                ]
          }
    }
}
```

```json [/ce-api/news?_content_format=markup]
{
    "title": "News Listing",
    "content_format": "markup",
    "content": "
      <teaser-listing title=\"Latest news\" icon=\"news\">
        <article-teaser to=\"https://example.com/news/1\" excerpt=\"The excerpt of the news entry.\" slot=\"default\"></article-teaser>
        <article-teaser to=\"https://example.com/news/2\" excerpt=\"The excerpt of another news entry.\" slot=\"default\"></article-teaser>
      </teaser-listing>"
}
```
::

## Multiple routes at one path

Note that the routing system supports routes at the same path with varying formats, thus a `html` and a `custom_elements` formatted route can co-exist at the same path. This may be used to clone routes and to customize them as needed.

```php

/**
 * Creates CE variants for user forms.
 */
class RouteSubscriber extends RouteSubscriberBase {

  /**
   * {@inheritdoc}
   */
  protected function alterRoutes(RouteCollection $collection) {
    // Provide CE variants for user forms.
    $form_route_ids = ['user.login', 'user.pass', 'user.register'];
    foreach ($form_route_ids as $form_route_id) {
      $route = $collection->get($form_route_id);
      $ce_route = clone $route;
      $ce_route->setRequirement('_format', 'custom_elements');
      // Then customize the new route as needed:
      $form = $route->hasDefault('_entity_form') ? 'entity_form' : 'form';
      $ce_route->setDefault('_controller', "lupus_decoupled_form.controller.$form:getContentResult");
      // Add it to the route collection.
      $collection->add("lupus_decoupled.{$form_route_id}", $ce_route);
    }
  }

}

```


# Providing blocks

In order to provide blocks that render into custom elements, for example for using as part of the [Layout Builder](lupus-decoupled.org/guide/layout-builder), the block cannot directly return a custom element object, since its interface requires a render array. Instead, simply return the custom element as render array via its helper `toRenderArray()`. When done so, the custom element is going to be picked up correctly when the layout is rendered.

## Example block

```php

/**
 * Provides an example news listing block.
 *
 * @Block(
 *   id = "lupus_decoupled_drupal_example_news_listing",
 *   admin_label = @Translation("Example news listing"),
 *   category = @Translation("Custom")
 * )
 */
class ExampleNewsListingBlock extends BlockBase {

  /**
   * {@inheritdoc}
   */
  public function build() {
    $articles[] = CustomElement::create('article-teaser')
      ->setAttribute('href', 'https://example.com/news/1')
      ->setAttribute('excerpt', 'The excerpt of the news entry.');
    $articles[] = CustomElement::create('article-teaser')
      ->setAttribute('href', 'https://example.com/news/2')
      ->setAttribute('excerpt', 'The excerpt of another news entry.');

    $teaser_listing = CustomElement::create('teaser-listing')
      ->setAttribute('title', 'Latest news')
      ->setAttribute('icon', 'news')
      ->setSlotFromNestedElements('default', $articles);

    // Return the custom element as render array to fulfill the interface.
    return $teaser_listing->toRenderArray();
  }

}
```


# Custom Element Processors

The custom elements module comes with Custom element processors that try to implement
a reasonable default for content entities and fields. These defaults can be
further customized with custom modules as needed.

The default entity processor renders the data of all visible fields either as
attribute to the custom element tag, or as nested markup via a slot. The module
maps simple fields and their properties to attributes and falls back to
rendering more complex fields to regular markup, which gets added as slot to
the parent custom element.

This method was the default in version 2.x and since 3.x, it's used when "Use automatic processing" is enabled in the Custom Elements display. Besides that, when "Auto" is selected for individual fields the field is formatted using processors.

Processors are provided via services, for example see [TextFieldItemProcessor](https://git.drupalcode.org/project/custom_elements/-/blob/3.x/src/Processor/TextFieldItemProcessor.php?ref_type=heads){rel="&#x22;nofollow&#x22;"} as registered at the [services.yml file](https://git.drupalcode.org/project/custom_elements/-/blob/3.x/custom_elements.services.yml?ref_type=heads){rel="&#x22;nofollow&#x22;"}.


# Adding Drupal forms

Lupus Decoupled Drupal supports submitting Drupal forms via the decoupled frontend, as documented under [Advanced Topics - Drupal Forms](lupus-decoupled.org/advanced-topics/drupal-forms).
In order to enable submitting another Drupal form on the frontend, a custom-elements enabled form processing route must be added. This is
done easily by:

1. Ensuring there is a custom-elements enabled route, e.g. by cloning the original one and
   adding `custom_elements` as `_format`.
2. Pointing the custom-elements enabled route to a form controller that renders the results as
   custom elements. For standard forms, the following controllers may be specified:

- For general forms: `lupus_decoupled_form.controller.form:getContentResult`
- For entity forms: `lupus_decoupled_form.controller.entity_form:getContentResult`:br Else, a custom controller can be easily be provided with the help of the `CustomElementsFormControllerTrait`,
  see the `lupus_decoupled_contact` submodule for an example.

That's it!

Generally, The [Lupus Decoupled Contact](https://git.drupalcode.org/project/lupus_decoupled/-/tree/1.x/modules/lupus_decoupled_contact){rel="&#x22;nofollow&#x22;"} module serves as
a simple example that demonstrates how support for contact forms is enabled.


# Providing Themes with JavaScript Rendering

## Overview

Lupus CSR (Client-Side Rendering) themes allow you to bundle a pre-built frontend application directly as a Drupal theme, so no separate frontend server is needed. Drupal serves the frontend's `index.html` for all frontend routes; the frontend loads in the browser and fetches content from the CE API at `/ce-api/...` on the same origin.

This approach is ideal for:

- Drupal CMS site templates where no separate frontend infrastructure is desired
- Getting started quickly without setting up a Node.js server
- Simple projects where SEO is not a primary concern

Note that client-side rendering means content is rendered in the browser via JavaScript. Search engines may not fully index CSR content. For production sites where SEO matters, use [server-side rendering](lupus-decoupled.org/nuxt/rendering-modes) instead.

## Lupus Client-Side Rendering (Lupus CSR)

[Lupus CSR](https://www.drupal.org/project/lupus_csr){rel="&#x22;nofollow&#x22;"} is the Drupal base theme that enables this pattern. It intercepts Drupal's normal HTML output and delivers the frontend's `index.html` instead. Because the frontend communicates with `/ce-api/...` on the same origin, CORS configuration is not needed and Drupal authentication works out of the box.

Install it via Composer:

```bash
composer require drupal/lupus_csr
```

### Using Lupus CSR Directly

The simplest approach: enable Lupus CSR as your active theme and configure it through the theme settings form at `/admin/appearance/settings/lupus_csr`. Set a separate admin theme (e.g. Claro) to keep the Drupal backend accessible.

The frontend redirect in Lupus Decoupled settings is not needed with theme-based rendering and can stay disabled.

### Creating a Sub-Theme

For distributable or project-specific setups, create a sub-theme of `lupus_csr` and include your frontend build output in a `dist/` directory. The `lupus_csr` module includes an example Nuxt starter in its `examples/` directory. Refer to the [Lupus CSR sub-theme guide](https://git.drupalcode.org/project/lupus_csr/-/blob/1.x/USAGE.md?ref_type=heads#lupus-csr---sub-theme-guide){rel="&#x22;nofollow&#x22;"} for configuration details.

### Canvas Integration

If the theme's preview provider supports it, components are automatically registered with [Canvas ExtJS](https://www.drupal.org/project/canvas_extjs){rel="&#x22;nofollow&#x22;"} when the theme is installed. The component index is read from the theme's bundled build output.


# Drupal Dev Days 2023 Videos

## Drupal Dev Days 2023 Video Recordings

- [Project Setup](https://video.bunnycdn.com/play/140086/22ceb9ad-53fb-4bd2-986c-068da185a6db){rel="&#x22;nofollow&#x22;"}
- [Adding a field](https://video.bunnycdn.com/play/140086/1d1fbe05-137b-4012-8bda-4bb60eb3398a){rel="&#x22;nofollow&#x22;"}
- [Preparing content](https://video.bunnycdn.com/play/140086/7dc67d51-7ca7-42a0-9cad-b1e07d5c15fb){rel="&#x22;nofollow&#x22;"}
- [Configure Views](https://video.bunnycdn.com/play/140086/8b16dac1-5fd7-4722-8529-beca9ed4dab4){rel="&#x22;nofollow&#x22;"}
- [Views Frontend](https://video.bunnycdn.com/play/140086/b559844b-96ed-4ac4-a9f2-7910b787c7f7){rel="&#x22;nofollow&#x22;"}
- [Layout builder](https://video.bunnycdn.com/play/140086/dc00b4a4-cac8-43d6-ad85-d1146f1b29e1){rel="&#x22;nofollow&#x22;"}


# Introduction

[Nuxt](https://nuxt.com){rel="&#x22;nofollow&#x22;"} is an open source framework under MIT license that makes web development simple and powerful.

- Like Drupal, it's extensible using [modules](https://nuxt.com/modules){rel="&#x22;nofollow&#x22;"}.
- Thanks to the [Drupal Custom Elements Connector module](https://github.com/drunomics/nuxtjs-drupal-ce){rel="&#x22;nofollow&#x22;"} Nuxt simply works with Lupus Decoupled Drupal.
- Thanks to [Vue.js](https://vuejs.org){rel="&#x22;nofollow&#x22;"} and its template-like [Single File Components](https://vuejs.org/guide/scaling-up/sfc.html){rel="&#x22;nofollow&#x22;"} it's easy to get started and developers can focus on writing standard HTML, CSS and JavaScript in their Vue components.

## Flexible hosting

With Nuxt you can decide what rendering strategy you want to use, if you like even at the route level: SSR, SSG, CSR. Build any kind of website or web application with optimized performance in mind.

## Outstanding performance

Nuxt comes with many optimizations, e.g. code-splitting, tree-shaking, link prefetching, payload extraction, just to name a few. It's built for serverless usage, has optimized cold-starts and is small enough to be deployed to the edge.

## SEO & Web Vitals

By leveraging server-side rendering, code-splitting and optimized images, Nuxt websites are indexable by search engines while providing an optimized user experience to end-users.

## Rich ecosystem

There are many useful [modules](https://nuxt.com/modules){rel="&#x22;nofollow&#x22;"} available that extend Nuxt, like [nuxt-i18n](https://nuxt.com/modules/i18n){rel="&#x22;nofollow&#x22;"} and [nuxt-seo](https://nuxt.com/modules/seo){rel="&#x22;nofollow&#x22;"}.

## Great DX

As usual, Nuxt comes with a built-in dev-mode that instantly hot-reloads during development (simply run `npm run dev`). Moreover, the [Nuxt devtools](https://nuxt.com/modules/devtools){rel="&#x22;nofollow&#x22;"} provide great in-browser dev-tooling and introspection possibilities.


# Setup

The [Drupal Custom Elements Connector](https://github.com/drunomics/nuxt-module-drupal-ce){rel="&#x22;nofollow&#x22;"} makes it easy to connect Nuxt with Lupus Decoupled Drupal and provide scaffold components to get started.

## Steps

1. Add the nuxt module `nuxtjs-drupal-ce` to your Nuxt project:

```bash
npx nuxi@latest module add drupal-ce
```

2. Configure the module in your nuxt config file `nuxt.config.js`

```js
export default defineNuxtConfig({
  modules: [
    'nuxtjs-drupal-ce',
  ],
  drupalCe: {
    drupalBaseUrl: 'https://your-drupal.example.com',
    // more options...
  }
})
```

The module defaults work well with [Lupus Decoupled Drupal](https://www.drupal.org/project/lupus_decoupled){rel="&#x22;nofollow&#x22;"}, so setting the `drupalBaseUrl` is usually enough. Howsoever, a complete list of options can be found in the module [README](https://github.com/drunomics/nuxtjs-drupal-ce/blob/2.x/README.md){rel="&#x22;nofollow&#x22;"}.

3. The module provides a set of scaffold files to get started quickly.

To generate the scaffold pages and components, run:

```bash
rm -f app.vue && npx nuxt-drupal-ce-init
```

The full list of scaffolded files is available in the [nuxtjs-drupal-ce repository](https://github.com/drunomics/nuxtjs-drupal-ce/tree/2.x/playground){rel="&#x22;nofollow&#x22;"}.


# Rendering Custom Elements

The [Drupal Custom Elements Connector](https://github.com/drunomics/nuxt-module-drupal-ce){rel="&#x22;nofollow&#x22;"} module allows you to render custom elements in your Nuxt.js application fetched from a Drupal backend.

## Basics

Generally, each custom element maps to a Vue component, which is automatically picked up when the component is named exactly like the custom element, e.g. for the element `drupal-markup` create the component `drupal-markup.vue`.

There is one gotcha though: For Vue to find your custom element components, they must be globally registered. Thus, in Nuxt, simply put them into your `components/global` folder, and they are picked up.

## Mapping attributes to props

Every attribute of a component is available in Vue's `$attrs` variable. However, it's best practice to define the props for the component, what makes each attribute available under its defined name:

```js
<template>
  <div class="node">
    <h2 v-if="title">Node: {{ title }}</h2>
  </div>
</template>

<script setup lang="ts">
defineProps<{
  title?: string;
}>()
</script>
```

## Rendering slots

Rendering slots in Vue components works seamlessly with both JSON and markup serialization. Simply use native Vue slots in your template:

```vue
<template>
  <slot name="body" />
</template>

<script setup lang="ts">
// Optional: Define slots for better TypeScript support
defineSlots<{
  body(): any;
}>()
</script>
```

This works with both JSON and markup serialization. The Nuxt Drupal CE connector automatically handles the slot content in both cases.

### JSON serialization (default)

With JSON-formatted custom elements, slot content is automatically mapped to Vue slots. You can use named slots or the default slot:

```vue
<template>
  <div class="card">
    <slot name="header" />
    <slot />
    <slot name="footer" />
  </div>
</template>

<script setup lang="ts">
// Optional: Define slots for TypeScript
defineSlots<{
  header(): any;
  default(): any;
  footer(): any;
}>()
</script>
```

Note: When rendering via JSON content, the module supports [default components](lupus-decoupled.org/nuxt/default-components).

### Markup serialization

With markup, the Vue template compiler needs to be enabled:

```js
// nuxt.config.js
export default {
  vue: {
    runtimeCompiler: true
  }
}
```

Then, slots will be directly passed as Vue slots.

```vue
  <slot name="body">Fallback content.</slot>
```

### Full example

Here is an example of a component that leverages props and slots and works with both markup and JSON serialization:

```vue
<template>
  <div class="node">
    <h2 v-if="title">Node: {{ title }}</h2>
    <slot name="body" />
  </div>
</template>

<script setup lang="ts">
// Optional: Define slots for TypeScript
defineSlots<{
  body(): any;
}>()
defineProps<{
  title?: string;
}>()
</script>
```


# Default components

**Note**: This feature is atm only available when using the (default) JSON-based rendered of custom elements.

## Overview

When using JSON-based rendering of custom elements, the module offers fallback component support. If a custom element lacks a corresponding Vue component, the module attempts to find a suitable default component.

## Use-case

This feature makes it possible to define a general custom element, e.g. for drupal forms `drupal-form--default.vue`, which is used to render every custom element `drupal-form-*` when no specific custom element is available. That way, specific elements provided by Drupal, e.g. `drupal-form-user-login-form.vue`, have the default applied, while it's easily possible to copy and customize the default component.

The same way it becomes handy to have general default components for content entities, like `node--default.vue`, paired with element names like `node-article-page`. That way it's easy to implement a general default component that suits multiple cases, while specific elements can easily be customized.

#### How it works:

1. The module removes the last `-`-separated prefix from the element name.
2. It then appends a `--default` suffix.
3. If this modified component exists, it's used for rendering.
4. If the component is not exiting, the process is repeated.

#### Example lookup process

When a specific component isn't found, the module searches for a default component by progressively removing segments from the custom element name. For example when rendering the custom element `node-custom-view` it looks for components in the following order:

```text
x node-custom-view.vue
x node-custom-view--default.vue
x node-custom--default.vue
✓ node--default.vue
```


# Composables

The composable provided by the module provides helpers to fetch page and menu data, handle errors, and render custom components.

### useDrupalCe

This composable exports a collection of utilities to handle Drupal content and functionality.

#### Page Handling

- `fetchPage(path: string, query?: Object, errorHandler?: Function, skipProxy?: boolean)` - Fetches a page by path
- `getPage()` - Returns the current page state
- `usePageHead(page: Ref<any>, include?: Array<'title' | 'meta' | 'link' | 'jsonld'>)` - Sets page head metadata from Drupal data
- `getPageLayout(page?: Ref<any>)` - Gets current page layout name (defaults to 'default')

#### Menu Handling

- `fetchMenu(name: string, options?: Object, errorHandler?: Function, skipProxy?: boolean)` - Fetches a menu by name

#### Component Rendering

- `renderCustomElements(elements: string | object | Array)` - Renders one or multiple custom elements from JSON data
- `resolveCustomElement(element: string)` - Resolves a custom element name to a Vue component
- `loadLibrary(library: Object)` - Loads a [Drupal JS library](lupus-decoupled.org/nuxt/drupal-libraries) emitted by the backend

#### Messages

- `getMessages()` - Returns Drupal messages of the current page

#### API Utilities

- `$ceApi(options?: Object, skipProxy?: boolean)` - Creates a configured fetch instance
- `useCeApi(path: string, options?: Object, passThroughHeaders?: boolean, skipProxy?: boolean)` - Fetches data from Drupal CE API endpoint
- `getCeApiEndpoint(localize?: boolean)` - Gets API endpoint with optional localization
- `getDrupalBaseUrl()` - Gets configured Drupal base URL
- `getMenuBaseUrl()` - Gets configured menu base URL

### Example usage

The following example makes use of the `fetchPage` method to get the current page:

```js
<script setup>
  const { fetchPage } = useDrupalCe()
  const page = await fetchPage(useRoute().path)
</script>
```


# Drupal JS libraries

## Overview

Drupal emits the JavaScript libraries attached to a rendered form, block or component as `<drupal-library-*>` custom elements. See [Drupal JavaScript](lupus-decoupled.org/advanced-topics/drupal-javascript) for what the backend sends and why; this page covers loading them in Nuxt.

## Rendering library elements

Add a global `drupal-library--default.vue` component - the [default component](lupus-decoupled.org/nuxt/default-components) lookup resolves it for every `drupal-library-*` element, whatever library the backend attached. A reference implementation is part of the playground: [drupal-library--default.vue](https://github.com/drunomics/nuxtjs-drupal-ce/blob/2.x/playground/components/global/drupal-library--default.vue){rel="&#x22;nofollow&#x22;"}.

The component is renderless: it takes the `library`, `js` and `drupalSettings` props of the element, hands them to `useDrupalCe().loadLibrary()` on mount, and renders nothing.

```vue
<script setup>
const props = defineProps({ js: Array, drupalSettings: String })
const { loadLibrary } = useDrupalCe()

onMounted(() => loadLibrary({ js: props.js, drupalSettings: props.drupalSettings }))
</script>
```

## loadLibrary()

`useDrupalCe().loadLibrary(library)` takes a resolved library (`{ js, drupalSettings }`) and returns a promise settling once its files have loaded. On the server it resolves immediately - loading is a client-side concern.

It lazy-loads the actual loader via a dynamic import, so the loader chunk - and the Drupal JavaScript it pulls in - is only fetched by pages that actually render a library element. The loader then:

- resolves the file URLs against the configured `drupalBaseUrl`,
- appends them as `<script>` tags, preserving execution order across all calls, so libraries load in the dependency order the backend resolved,
- loads each URL only once, even when several libraries share a file,
- merges `drupalSettings` into `window.drupalSettings` before any script runs,
- calls `Drupal.attachBehaviors()` once the batch has loaded, so behaviours attach to the server-rendered markup,
- skips a file that fails to load with a console warning, rather than aborting the batch.

The `attributes` a library declares for its `<script>` tags are currently not applied.

## Overriding or skipping a library

To replace a library with a native implementation, add a component named after its element tag - `drupal-library-core-drupal-states.vue` for `core/drupal.states`. It takes precedence over the default component, so the library's JavaScript is never loaded. A component that renders nothing and does nothing skips the library entirely.

## Trying it out

The playground has a form whose conditional field is driven by `core/drupal.states` at [/form/states](https://github.com/drunomics/nuxtjs-drupal-ce/blob/2.x/playground/server/routes/ce-api/form/states.get.ts){rel="&#x22;nofollow&#x22;"}, served by a mock Custom Elements API response - a working example of the whole path, from the emitted elements to the attached behaviour.


# Custom Routes

Custom frontend routes are routes that are not defined in Drupal. They are defined in the frontend and can be used create custom pages.

## Routing overview

In your Nuxt application, the routing mechanism runs in the following order:

1. **Nuxt Routing:** It attempts to align the navigated path with one of the predefined routes located in your `pages` directory.
2. **Nuxt Route Fallback:** If no predefined routes match, the system defaults to the wildcard route `pages/[...slug].vue`. This wildcard route forwards requests to Drupal, such that the regular Drupal routing can handle the request.

## Defining frontend routes

In the frontend, the Drupal routing is managed by the wildcard `pages/[...slug].vue` file within the pages directory.

In order to create a custom route in the frontend:

1. Go to the `pages` directory.
2. Create a new file with the desired route name. For instance, if you want a route named `search`, create a file called `search.vue`.

For more information on routing in Nuxt, see the [Nuxt routing documentation](https://nuxt.com/docs/getting-started/routing){rel="&#x22;nofollow&#x22;"}.

## Handling route misses

In the event that no matching route is found by Drupal, by default, error pages provided by Drupal (e.g. 403, 404 page) are shown, while keeping the right status code. However, it's possible to take-over error handling in Nuxt as well. Please refer to the [error handling topic](lupus-decoupled.org/advanced-topics/error-pages).


# Page Layouts

Nuxt layouts are placed in the `./layouts` directory and are used to define a shared [site layout](lupus-decoupled.org/guide/site-layout-menus)
for a group of pages. When a page has a different layout, nuxt takes care of swapping the layout component(s).

For example, you can have a `default.vue` layout that is used for most pages, and a `blog.vue` layout that is used for
all blog posts.

## Create a layout

To create a layout, simply create a `.vue` file in the `./layouts` directory.

```vue
<template>
  <div>
    <h1>Blog layout</h1>
    <slot />
  </div>
</template>
```

## Drupal controlled layouts

The Drupal page API comes with a `page_layout` attribute within its response. By default, this is used to control which
layout is applied by Nuxt. This allows Drupal code to customize the layout used by Nuxt.

To set a custom layout from within Drupal, the `page_layout` attribute must be set accordingly, e.g. via
`hook_lupus_ce_renderer_response_alter()`.

## Setting the layout in the frontend

The frontend may set a custom layout by proving a custom page component for some routes. For example, to change the
layout for all `/news/*` routes controlled by Drupal via the page API, create a component `news/[...slug].vue` in the
pages directory of Nuxt. Then make the page component follow the logic of the default page component, but override the
layout to be hard-coded:

```vue
<script lang="ts">
  import DefaultPage from '../[...slug].vue'

  export default {
    extends: DefaultPage,
    async setup() {
      const { fetchPage, renderCustomElements, usePageHead, getPageLayout } = useDrupalCe()
      const page = await fetchPage(useRoute().path, {
        query: useRoute().query,
      }, undefined, true)

      const layout = 'custom'
      usePageHead(page)

      return {
        page,
        layout,
        renderCustomElements,
      }
    },
  }
</script>
```

## Nuxt layout documentation

For more information on routing in Nuxt.js, see the [Nuxt layouts documentation](https://nuxt.com/docs/guide/directory-structure/layouts){rel="&#x22;nofollow&#x22;"}.


# Component Previews

Component previews allow Vue components to be rendered in isolation in external contexts, such as the [Drupal Canvas](lupus-decoupled.org/guide/canvas) editor. This enables editors to see live previews of components directly in the page builder.

[nuxt-component-preview](https://github.com/drunomics/nuxt-component-preview){rel="&#x22;nofollow&#x22;"} implements this for Nuxt/Vue. It enables previewing components in external contexts and auto-generates a component index for [Drupal Canvas](lupus-decoupled.org/guide/canvas) integration.

If you are using the [Nuxt Starter](https://github.com/drunomics/lupus-decoupled-nuxt-starter){rel="&#x22;nofollow&#x22;"} or [nuxtjs-drupal-ce](https://github.com/drunomics/nuxtjs-drupal-ce){rel="&#x22;nofollow&#x22;"}, the module is already pre-configured — no setup needed.

## Component Index

The same module also auto-generates a [component index](lupus-decoupled.org/nuxt/canvas-components) that Canvas uses to discover the available components, their props, and their metadata.

## Manual Setup

If you are not using the Nuxt Starter or nuxtjs-drupal-ce, install and configure the module manually.

Install the module:

```bash
npm install nuxt-component-preview
```

Add it to `nuxt.config.ts` and add `<ComponentPreviewArea />` to `app.vue`:

```ts
export default defineNuxtConfig({
  modules: ['nuxt-component-preview'],
})
```

```vue
<template>
  <ComponentPreviewArea v-if="useRuntimeConfig().public.componentPreview" />
  <NuxtPage v-else />
</template>
```

When embedding previews from a different domain (e.g. a Drupal backend), disable the app manifest in development to avoid relative URL failures:

```ts
$development: {
  experimental: {
    appManifest: false
  }
}
```

For CORS configuration, see the [nuxt-component-preview CORS setup](https://github.com/drunomics/nuxt-component-preview#cors-configuration){rel="&#x22;nofollow&#x22;"}. When using nuxtjs-drupal-ce, CORS is configured automatically.


# Component Index

To make Vue components available in the [Drupal Canvas](lupus-decoupled.org/guide/canvas) editor, the frontend exposes a **component index**: a JSON file listing all available components together with their props, prop schemas, labels, descriptions, categories, formats and schema references. [Canvas External JS Components](https://www.drupal.org/project/canvas_extjs){rel="&#x22;nofollow&#x22;"} reads this index and uses it to populate the editor UI.

The [nuxt-component-preview](https://github.com/drunomics/nuxt-component-preview){rel="&#x22;nofollow&#x22;"} Nuxt module generates this index automatically from your components, picking up extra metadata from JSDoc annotations (implemented in [`src/runtime/server/utils/`](https://github.com/drunomics/nuxt-component-preview/tree/1.x/src/runtime/server/utils){rel="&#x22;nofollow&#x22;"}). The same module also powers the [Component Previews](lupus-decoupled.org/nuxt/component-previews) used by the Canvas editor.

The index is served at `/nuxt-component-preview/component-index.json`.

Only **global** components are included. Components in `components/global/` are automatically global; others can be registered with `global: true` in `nuxt.config.ts`.

## Grouping Components by Folder

A recommended pattern is to keep Canvas components in a dedicated `components/Canvas/` folder and derive categories from subfolder names:

```ts
components: [
  { path: '~/components/Canvas', global: true, pathPrefix: false, prefix: '' },
  { path: '~/components/global', global: true },
  '~/components',
],

componentPreview: {
  componentIndex: {
    // Derive Canvas component categories from folder names (Base/, Layout/, Card/, Hero/)
    category: { directory: true, fallback: 'Misc' },
  },
},
```

For working examples, see the [Canvas components in the Lupus Decoupled Nuxt Starter](https://github.com/drunomics/lupus-decoupled-nuxt-starter/tree/main/components/Canvas){rel="&#x22;nofollow&#x22;"}.

## JSDoc Metadata

Components and their props are documented via TypeScript, with JSDoc annotations supplying the additional metadata that TypeScript alone cannot express. The pattern is consistent: a label (display name) and an optional description, plus additional tags.

### Component Metadata

Define component-level metadata via a JSDoc comment at the top of `<script setup>`:

```vue
<script setup lang="ts">
/**
 * Hero Billboard
 * @description A full-width hero section with background image and overlay.
 * @category Hero
 * @status stable
 */
</script>
```

| Tag            | Description                                                         |
| -------------- | ------------------------------------------------------------------- |
| First line     | Label / display name (falls back to auto-generated from PascalCase) |
| `@description` | Component description shown in the editor                           |
| `@category`    | Category override (alternative to directory-based)                  |
| `@status`      | `experimental`, `stable`, `deprecated`, or `obsolete`               |

All fields are optional. Config-level overrides take priority over JSDoc.

### Prop Metadata

Props follow the same pattern — a label and description, plus additional tags for editor behavior:

```vue
<script setup lang="ts">
withDefaults(defineProps<{
  /**
   * Button label text
   * @example Submit
   */
  label?: string
  /**
   * Button variant
   * @enumLabels {"large": "Extra Large (XL)"}
   */
  variant?: 'primary' | 'secondary' | 'large'
}>(), {
  label: 'Click me',
  variant: 'primary'
})
</script>
```

The prop label is auto-generated from the first JSDoc line or prop name. Use `@title` to override.

| Tag                               | Description                                                                                                                                                                                                  |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `@title`                          | Explicit label override                                                                                                                                                                                      |
| `@example`                        | Adds example values (multiple allowed)                                                                                                                                                                       |
| `@enumLabels`                     | Custom labels for enum values, e.g. `{"large": "Extra Large (XL)"}`                                                                                                                                          |
| `@contentMediaType text/html`     | Enables rich text editing in Canvas for string props                                                                                                                                                         |
| `@formattingContext block|inline` | Controls formatting context (default: `block`)                                                                                                                                                               |
| `@schemaRef`                      | Reference Canvas JSON schema definitions (e.g. `canvas/stream-wrapper-uri`); array variant: `@itemsSchemaRef`                                                                                                |
| `@format`                         | JSON Schema format for semantic validation and UI widgets: `date`, `date-time`, `time`, `duration`, `email`, `hostname`, `ipv4`, `ipv6`, `uuid`, `uri`, `uri-reference`, etc.; array variant: `@itemsFormat` |
| `@pattern`                        | JSON Schema regex pattern for string validation                                                                                                                                                              |
| `@allowed-schemes`                | Allowed URI schemes for Canvas field type detection (e.g. `public` or `http, https`)                                                                                                                         |
| `@minItems` / `@maxItems`         | Cardinality bounds for array props (see [Multi-Value Props](lupus-decoupled.org/#multi-value-array-props))                                                                                                   |

## Drupal Canvas Types

For Canvas integration, special TypeScript types are available that generate JSON schemas enabling Canvas UI features like media library selection. These types are auto-imported by Nuxt.

| Type          | Description                                                    |
| ------------- | -------------------------------------------------------------- |
| `CanvasImage` | Image with media library integration (src, alt, width, height) |
| `CanvasVideo` | Video with poster support                                      |

Example usage:

```vue
<script setup lang="ts">
/**
 * Hero Banner
 */
defineProps<{
  /**
   * Background image
   * @example src=https://example.com/hero.jpg alt="Hero" width=1200 height=600
   */
  image: CanvasImage
}>()
</script>
```

The `@example` for Canvas types supports two formats:

- Key-value: `src=https://... alt="text" width=800 height=600`
- JS object: `{ src: 'https://...', alt: 'text', width: 800 }`

### Schema References

For advanced use cases, `@schemaRef` allows referencing Canvas JSON schema definitions directly, useful for types like `stream-wrapper-uri` and `stream-wrapper-image-uri`. Use the shorthand `prefix/name` notation:

```vue
/**
 * @schemaRef canvas/stream-wrapper-uri
 */
imageUri?: string
```

This expands to `json-schema-definitions://canvas.module/stream-wrapper-uri`.

## Multi-Value (Array) Props

Canvas 1.4 introduced support for multi-value props — arrays of primitives, formatted strings, enums, or known struct shapes. Declare them as TS array types; refinements TypeScript can't express are picked up via JSDoc.

### Cardinality

| Tag           | Effect                                                                          |
| ------------- | ------------------------------------------------------------------------------- |
| `@minItems N` | Required-array — canvas treats this as the multi-value equivalent of `required` |
| `@maxItems N` | Caps the number of entries                                                      |

### Element-shape refinements (applied to `items`)

| Tag                             | Effect                                                                                                                                              |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `@itemsFormat <fmt>`            | Lifts `format` into `items` (e.g. `uri`, `uri-reference`, `date`, `date-time`, `email`)                                                             |
| `@itemsSchemaRef <prefix/name>` | Lifts `$ref` into `items`, including known-shape extras (`format`, `x-allowed-schemes`, `contentMediaType`) — same as `@schemaRef` for scalar props |

### Enums in items

TypeScript union literals on the element type lift into `items.enum` + auto-generated `items.meta:enum` labels. `@enumLabels` on the prop overrides those labels.

```vue
<script setup lang="ts">
defineProps<{
  // Element labels auto-generated from values.
  status?: ('option_one' | 'option_two' | 'option_three')[]

  /**
   * @enumLabels {"draft": "Draft", "review": "In Review", "live": "Live"}
   */
  workflowState?: ('draft' | 'review' | 'live')[]

  // Numeric union → items.type: integer + enum.
  ratings?: (1 | 2 | 3 | 4 | 5)[]
}>()
</script>
```

### Full example

```vue
<script setup lang="ts">
withDefaults(defineProps<{
  /**
   * Plain text values
   * @example ["Hello World", "Sample Text"]
   */
  textValues?: string[]

  /**
   * Required text values (canvas signals required via minItems)
   * @minItems 1
   */
  requiredText: string[]

  /**
   * Absolute URLs, capped at 3
   * @itemsFormat uri
   * @maxItems 3
   */
  links?: string[]

  /**
   * Event dates
   * @itemsFormat date
   */
  dates?: string[]

  /**
   * Workflow state list — labels overridden via @enumLabels
   * @enumLabels {"draft": "Draft", "review": "In Review", "live": "Live"}
   * @maxItems 3
   */
  states?: ('draft' | 'review' | 'live')[]

  /**
   * Public file attachments
   * @itemsSchemaRef canvas/stream-wrapper-uri
   */
  attachments?: string[]

  /**
   * Gallery images
   * @maxItems 5
   */
  images?: CanvasImage[]
}>(), {})
</script>
```

A complete example covering every shape combination can be seen in [TestMultiValueProps.vue](https://github.com/drunomics/nuxt-component-preview/blob/1.x/playground/components/global/TestMultiValueProps.vue){rel="&#x22;nofollow&#x22;"} and its [generated component-index](https://github.com/drunomics/nuxt-component-preview/blob/1.x/test/fixtures/multivalue-props.component-index.json){rel="&#x22;nofollow&#x22;"}.


# Rendering modes

With Nuxt you can decide what rendering strategy you want to use, if you like even at the route level.

**Please refer
to the Nuxt documentation about [Rendering modes](https://nuxt.com/docs/guide/concepts/rendering){rel="&#x22;nofollow&#x22;"} to learn more.**

The following provides some additional overview about implication of each rendering mode when using it with Lupus Decoupled Drupal:

## Server-side Rendering (SSR) - default

Server-side rendering is used as a default, which is best for SEO, and works the most seamlessly for editors thanks to the
support of Drupal authentication. Nuxt supports server-rendering via regular (Node.js) servers or in a serverless way, e.g. at the [edge](https://nuxt.com/docs/guide/concepts/rendering#edge-side-rendering){rel="&#x22;nofollow&#x22;"}.

## Static-site Generation (SSG)

Static-site generation results in a set of pre-generated files which a regular HTTP server or a CDN can serve, what can help to
make hosting much more simple.

Additionally, by publishing only static files, site security can be improved. However, there is also a drawback:
Editors need to be aware of the pre-rendering step, the frontend is static and no drupal-forms are supported (atm). Nuxt supports a [preview-mode](https://nuxt.com/docs/api/composables/use-preview-mode#usepreviewmode){rel="&#x22;nofollow&#x22;"} which can be implemented and provided to editors though. Read more about it in the Nuxt [Prerendering Guide](https://nuxt.com/docs/getting-started/prerendering){rel="&#x22;nofollow&#x22;"}.

## Client-side Rendering (CSR)

When SEO is not important and a small client-side rendering delay is acceptable to users, client-side rendering can
be a simple alternative to server-side rendering, that does not require any special infrastructure.

Just like with SSG, simply hosting static files is enough. At the moment, no drupal-forms are supported, but Drupal authentication works with the help of the Lupus Decoupled CORS sub-module.

For a zero-infrastructure alternative, see [Providing Themes](lupus-decoupled.org/drupal/themes): [Lupus CSR](https://www.drupal.org/project/lupus_csr){rel="&#x22;nofollow&#x22;"} allows bundling the frontend directly as a Drupal theme, with no separate frontend needed. The frontend is served from Drupal and fetches content from the CE API on the same origin.


# Deployment options

The deployment of Nuxt largely depends on the frontend [rendering mode](lupus-decoupled.org/nuxt/rendering-modes) chosen. Please refer to the
Nuxt [deployment guide](https://nuxt.com/docs/getting-started/deployment){rel="&#x22;nofollow&#x22;"} for additional details.

## Server-rendered

- **Run a Node.js Server** - Useful for deploying Nuxt apps to any Node.js hosting. [Details](https://nuxt.com/docs/getting-started/deployment#nodejs-server){rel="&#x22;nofollow&#x22;"}
- **Edge-Side Rendering** - Run nuxt close to the user, e.g. at edge servers of a CDN. [Details](https://nuxt.com/docs/guide/concepts/rendering#edge-side-rendering){rel="&#x22;nofollow&#x22;"}

Nuxt uses Nitro as its server framework. Thus, also refer to the [Nitro deployment documentation](https://nitro.build/deploy){rel="&#x22;nofollow&#x22;"} for additional details.
For deployments via Docker, an example Dockerfile can be found [here](https://nitro.build/deploy/providers/koyeb#using-a-docker-container){rel="&#x22;nofollow&#x22;"}.

## Static hosting

- **Static Site Generation** prerenders the site during build time. [Details](https://nuxt.com/docs/getting-started/deployment#static-hosting){rel="&#x22;nofollow&#x22;"}
- **Client-side rendering** renders everything the browser. [Details](https://nuxt.com/docs/getting-started/deployment#client-side-only-rendering){rel="&#x22;nofollow&#x22;"}

For serving static files a general web-server is generally good-enough, additionally there are [deployment presets](https://nuxt.com/deploy){rel="&#x22;nofollow&#x22;"} available that make it
easy to trigger the pre-rendering process and serve the resulting build, e.g. with Github or Gitlab pages.

## Supported presets

Nuxt comes with lots of supported presets. Refer to the [Nuxt deployment presets](https://nuxt.com/deploy){rel="&#x22;nofollow&#x22;"}.


# Resources

## Lupus Decoupled Nuxt resources

- [Nuxt Drupal CE Connector](https://github.com/drunomics/nuxtjs-drupal-ce){rel="&#x22;nofollow&#x22;"}
- [Naked demo project](https://github.com/drunomics/lupus-decoupled-nuxt3-demo){rel="&#x22;nofollow&#x22;"}
- [Shad-CN Demo project](https://github.com/drunomics/lupus-decoupled-nuxt3-demo-shadcn){rel="&#x22;nofollow&#x22;"}

### Legacy

- [Nuxt 2 demo project (legacy)](https://github.com/drunomics/lupus-decoupled-nuxt-demo){rel="&#x22;nofollow&#x22;"}

## General Nuxt resources

- [Nuxt website](https://nuxt.com){rel="&#x22;nofollow&#x22;"}
- [Nuxt docs](https://nuxt.com/docs){rel="&#x22;nofollow&#x22;"}
- [Nuxt modules](https://nuxt.com/modules){rel="&#x22;nofollow&#x22;"}


# Deployment Strategies

Lupus Decoupled Drupal supports two fundamentally different deployment approaches: running the frontend as a separate service, or bundling it directly as a Drupal theme.

## Separate Frontend

With a separate frontend, a standalone frontend server (e.g. a Node.js/Nuxt server) handles page rendering and communicates with Drupal via the CE API. This is the default approach for production sites where SSR or SSG is needed.

Within this approach, there are two hosting strategies:

### Separated Deployment

The frontend and Drupal backend are deployed and hosted independently. This offers:

- Faster frontend deployments without dependency on Drupal maintenance windows
- Freedom to choose specialized frontend hosting solutions (e.g. serverless edge deployments)
- Independent scaling and optimization of each component

However, this adds complexity in coordinating multiple environments. For Nuxt frontends, see the [Nuxt deployment docs](lupus-decoupled.org/nuxt/deployment).

### Unified Deployment

Frontend and Drupal backend are hosted together in a single environment. This:

- Requires a hosting environment capable of running both frontend (e.g. Node.js) and Drupal
- Simplifies deployment coordination and environment management
- Enables direct communication between services (e.g. cache or search servers)

A list of unified hosting possibilities can be found [here](lupus-decoupled.org/deployment/unified-hosting).

### Frontend Rendering Modes

Both strategies support multiple rendering modes (SSR, SSG, CSR). By default, Lupus Decoupled uses a Nuxt frontend with server-side rendering. Refer to the [Nuxt rendering modes](lupus-decoupled.org/nuxt/rendering-modes) or your frontend framework's documentation for details.

## Theme-Based Deployment (CSR)

With [Lupus CSR](https://www.drupal.org/project/lupus_csr){rel="&#x22;nofollow&#x22;"}, the pre-built frontend application is bundled directly as a Drupal theme. No separate frontend server is needed:

- Any standard Drupal hosting works
- The frontend application is deployed alongside Drupal as part of the theme
- It fetches content from `/ce-api/...` on the same origin

This is the simplest deployment strategy and the default for [Drupal CMS site templates](lupus-decoupled.org/advanced-topics/site-templates). The trade-off is client-side rendering, which is not ideal for SEO-critical sites.


# Unified Hosting

## Unified hosting options

::note
If you are using 

[theme-based deployment](lupus-decoupled.org/deployment/deployment-strategy#theme-based-deployment-csr)

, any standard Drupal hosting works without Node.js support. The options below are for setups with a separate frontend server.
::

The following (in-complete) list of hosting providers offer specialized Drupal hosting while being able to host a decoupled
frontend.

### Amazee.io

Amazee.io provides a managed open source hosting platform based on Kubernetes. It offers [Drupal hosting](https://www.amazee.io/drupal){rel="&#x22;nofollow&#x22;"} and Node.js
support. It provides the flexibility to add backend and frontend in one project, or as separate projects.

### Pantheon.io

Pantheon.io offers [Drupal hosting](https://pantheon.io/product/drupal-hosting){rel="&#x22;nofollow&#x22;"} and optionally a decoupled [frontend site](https://pantheon.io/features/decoupled-cms){rel="&#x22;nofollow&#x22;"}
as well. Still, the frontend is deployed separately from the backend, so each system can be deployed on its own.

See the [Deploy on Pantheon](lupus-decoupled.org/deployment/pantheon) guide for step-by-step instructions.

### upsun

upsun (by platform.sh) is a cloud application platform. It offers [Drupal support](https://devcenter.upsun.com/posts/drupal-and-upsun/){rel="&#x22;nofollow&#x22;"} as well as [Node.js support](https://docs.upsun.com/get-started/here/configure/nodejs.html){rel="&#x22;nofollow&#x22;"}. Depending on the
configuration, frontend and backend can be deployed as a single app, or as two separate apps.


# Deploy on Pantheon

::warning
Pantheon's Next.js hosting is currently in 

**invite-only beta**

. You need beta access enabled on your Pantheon workspace before you can create Next.js sites.
::

Pantheon's [Next.js Beta](https://docs.pantheon.io/guides/decoupled/nextjs){rel="&#x22;nofollow&#x22;"} hosting supports deploying **Next.js** frontends with Lupus Decoupled Drupal. Since the platform uses a framework-agnostic Node.js build pipeline under the hood, **Nuxt** frontends also work.

## Prerequisites

- A Pantheon workspace with Next.js Beta access enabled
- A Drupal site with [lupus\_decoupled](https://www.drupal.org/project/lupus_decoupled){rel="&#x22;nofollow&#x22;"} installed and the custom elements API working
- A GitHub account connected to your Pantheon workspace

## Step 1: Create the frontend site on Pantheon

1. Go to Pantheon Dashboard → **Add Site** → **Next.js**
2. Choose &#x2A;*"Create new repository"**

::warning
Do 

**not**

 use "Connect existing repository" — it fails silently without any error message. Let Pantheon create the repo first, then push your code to it.
::

3. Wait for the initial template deployment to succeed
4. Note the GitHub repo that was created (e.g. `your-org/your-site-name`)

## Step 2: Prepare your frontend

Clone a Lupus Decoupled frontend starter:

::code-group
```bash [Nuxt]
git clone https://github.com/drunomics/lupus-decoupled-nuxt-starter.git my-frontend
```

```bash [Next.js]
git clone https://github.com/drunomics/lupus-decoupled-nextjs-example.git my-frontend
```
::

Configure it to point at your Pantheon Drupal backend. The recommended approach is to set the Drupal base URL as an environment variable on Pantheon via **Dashboard → Settings → Environment Variables** (only available after the first successful deployment):

::code-group
```bash [Nuxt]
NUXT_PUBLIC_DRUPAL_CE_DRUPAL_BASE_URL=https://dev-your-drupal-site.pantheonsite.io
```

```bash [Next.js]
NEXT_PUBLIC_DRUPAL_BASE_URL=https://dev-your-drupal-site.pantheonsite.io
```
::

Alternatively, you can set the base URL directly in the framework config:

::code-group
```ts [Nuxt — nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['nuxtjs-drupal-ce'],
  drupalCe: {
    drupalBaseUrl: 'https://dev-your-drupal-site.pantheonsite.io',
  },
})
```

```ts [Next.js — .env.local]
NEXT_PUBLIC_DRUPAL_BASE_URL=https://dev-your-drupal-site.pantheonsite.io
```
::

::note
For Nuxt, all 

`nuxtjs-drupal-ce`

 options can be overridden at runtime via 

`NUXT_PUBLIC_DRUPAL_CE_*`

 environment variables. See the 

[nuxtjs-drupal-ce documentation](https://www.drupal.org/project/lupus_decoupled/wiki/nuxtjs-drupal-ce){rel=""nofollow""}

 for details.
::

## Step 3: Push to Pantheon

Push your frontend code to the GitHub repo Pantheon created:

```bash
cd my-frontend
rm -rf .git
git init && git add -A && git commit -m "Initial deploy"
git remote add origin git@github.com:your-org/your-pantheon-repo.git
git branch -m main
git push --force origin main
```

## Step 4: Wait for the build

Pantheon builds automatically on push. This typically takes 5–10 minutes.

You can check deployment status via the GitHub API:

```bash
gh api repos/your-org/your-repo/deployments --jq '.[0].statuses_url' | xargs gh api --jq '.[0].state'
```

## Step 5: Verify

Visit `https://dev-your-frontend-site.pantheonsite.io/`. You may need to click through Pantheon's sandbox page on first visit. Your Drupal content should render through the frontend.

## Node.js version

Pantheon auto-detects the Node.js version from the `engines` field in `package.json`. If not specified, it defaults to Node.js LTS (currently v22).

```json
{
  "engines": {
    "node": ">=22"
  }
}
```