Lupus Decoupled Drupal

Arquitectura Drupal desacoplada lista para usar que proporciona una API de custom elements para construir sitios Drupal headless con Nuxt.js u otros frontends JavaScript.

lupus_decoupled
84 sites
35
drupal.org
api integration gui
decoupled headless API nuxt vue custom-elements json frontend rest cors ssg ssr
Drupal 9 Drupal 10 Drupal 11

Install

Drupal 11, 10 v1.4.1
composer require 'drupal/lupus_decoupled:^1.4'
Drupal 9 v1.1.0
composer require 'drupal/lupus_decoupled:^1.1'

Overview

Lupus Decoupled Drupal es una solución de arquitectura desacoplada integral que permite a Drupal servir contenido a través de una API de Custom Elements en /ce-api. Transforma el renderizado de contenido de Drupal en respuestas JSON que contienen definiciones de custom elements que pueden ser consumidas por frontends JavaScript como Nuxt.js.

El módulo proporciona un conjunto completo de submódulos para manejar diversas características de Drupal en un contexto desacoplado, incluyendo formularios, views, bloques, menús, webforms, formularios de contacto, autenticación de usuarios y más. Redirige automáticamente las rutas del frontend a la URL del frontend configurada, procesa las URLs de archivos para que sean absolutas y gestiona la configuración de CORS.

La arquitectura utiliza el ecosistema del módulo Custom Elements (custom_elements, lupus_ce_renderer) para convertir los render arrays de Drupal en datos JSON estructurados que representan web components. Esto permite una separación clara entre Drupal como backend de contenido y los frameworks JavaScript modernos como capa de presentación.

Features

  • Proporciona un endpoint de API de Custom Elements en /ce-api que transforma el contenido de Drupal en respuestas JSON
  • Redirección automática de rutas del frontend: redirige las páginas de nodos de Drupal a la URL del frontend configurada
  • Genera URLs de archivos absolutas en las respuestas de la API para el manejo adecuado de assets en frontends desacoplados
  • Configuración de CORS para permitir que el JavaScript del frontend acceda a las APIs de Drupal desde el navegador
  • Integración de endpoints de API de menús mediante el módulo rest_menu_items para servir menús de Drupal a los frontends
  • Integración con Views mediante plugins de display Custom Elements Page y Block para renderizar views como custom elements
  • Soporte de renderizado de formularios: envuelve los formularios de Drupal en custom elements para envíos de formularios progresivos
  • Integración de formularios de contacto para servir formularios de contacto de Drupal a frontends desacoplados
  • Integración con el módulo Webform para exponer webforms a través de la API de custom elements
  • Soporte de formularios de autenticación de usuarios (inicio de sesión, restablecimiento de contraseña) para flujos de autenticación en el frontend
  • Integración con Layout Builder para usar el Layout Builder de Drupal con salida de custom elements
  • Integración con el diseño de bloques que añade regiones de bloques a las respuestas de la API
  • Recurso REST de información del sitio en /api/site-info para exponer valores de configuración del sitio configurables
  • Soporte de Schema Metatag/JSON-LD para datos estructurados en las respuestas de la API
  • Integración de vista previa responsive para previsualizar el frontend desacoplado en el admin de Drupal
  • Integración de registro de solicitudes/respuestas de API con el módulo REST Log para depuración
  • Sistema de proveedor de vista previa para renderizar previsualizaciones de componentes en interfaces administrativas
  • Soporte de variables de entorno (DRUPAL_FRONTEND_BASE_URL) para la configuración de la URL del frontend

Use Cases

Construir un frontend Nuxt.js para un sitio Drupal

Usa Lupus Decoupled para servir contenido de Drupal a un frontend Nuxt.js. Instala el módulo, configura la URL base del frontend y usa el conector nuxtjs-drupal-ce en tu aplicación Nuxt. El endpoint /ce-api servirá respuestas JSON que la aplicación Nuxt puede renderizar como componentes Vue.

Implementar autenticación de usuarios en un frontend desacoplado

Habilita lupus_decoupled_user_form para exponer los formularios de inicio de sesión y restablecimiento de contraseña de Drupal. El frontend recibe HTML de formularios renderizado en el servidor envuelto en custom elements, permitiendo mejora progresiva mientras mantiene las características de seguridad de Drupal.

Crear páginas de listado con Views

Usa lupus_decoupled_views para crear páginas de listado que generan custom elements. Añade un display Custom Elements Page a tu view, configura el nombre del custom element y los resultados de la view se servirán como JSON con soporte completo de paginación.

Exponer webforms al frontend

Habilita lupus_decoupled_webform para hacer accesibles los webforms de Drupal a través de la API de custom elements. Los usuarios pueden enviar formularios en el frontend y los mensajes de confirmación son gestionados por el sistema de webforms de Drupal.

Arquitectura multi-frontend

Configura múltiples URLs base de frontend usando el parámetro del contenedor lupus_decoupled_ce_api.frontend_base_urls. Esto permite que un único backend de Drupal sirva contenido a múltiples aplicaciones frontend con la configuración de CORS adecuada.

Depurar respuestas de API durante el desarrollo

Habilita lupus_decoupled_api_log para registrar todas las solicitudes y respuestas de API. Configura REST Log en /admin/config/development/logging/rest_log e investiga las solicitudes registradas en /admin/reports/rest_log para solucionar problemas de comunicación frontend-backend.

Servir configuración del sitio al frontend

Usa lupus_decoupled_site_info para exponer configuraciones del sitio como nombre, eslogan y email de contacto mediante /api/site-info. Configura valores adicionales usando drush config:edit lupus_decoupled_site_info.settings con el formato {config_name}:{config_key}.

Diseños basados en bloques en sitios desacoplados

Habilita lupus_decoupled_block para incluir regiones de bloques en las respuestas de la API. Coloca bloques en /admin/structure/block y automáticamente se renderizarán e incluirán en la propiedad 'blocks' de la respuesta de la API para las rutas correspondientes.

Tips

  • Usa la plantilla del proyecto en https://github.com/drunomics/lupus-decoupled-project para un inicio rápido con una configuración preconfigurada de Drupal + Nuxt.js incluyendo soporte para ddev y Gitpod.
  • El parámetro de consulta ?auth=1 se añade automáticamente al guardar nodos para ayudar a los frontends generados estáticamente a obtener contenido fresco inmediatamente.
  • Para tematizar elementos de formulario con markup limpio, considera usar el tema lupus-stark (drupal/lupus_stark) que elimina el markup innecesario específico de Drupal.
  • El prefijo de API (/ce-api) puede personalizarse mediante el parámetro del contenedor lupus_decoupled_ce_api.api_prefix si es necesario.
  • Habilita lupus_decoupled_api_log durante el desarrollo para depuración rápida de solicitudes y respuestas de API.
  • Al configurar múltiples frontends, añade URLs base adicionales a lupus_decoupled_ce_api.frontend_base_urls para un manejo adecuado de CORS.
  • Los nombres de custom elements para Views pueden sobrescribirse en la configuración del display para coincidir con las convenciones de nomenclatura de componentes de tu frontend.
  • El formato de contenido (json vs markup) puede configurarse mediante el parámetro lupus_decoupled_ce_api.content_format.
  • Consulta https://lupus-decoupled.org para documentación completa y tutoriales.

Technical Details

Admin Pages 1
Configuración de Lupus Decoupled Drupal /admin/config/system/lupus-decoupled/settings

Configura la conexión entre tu backend Drupal y el frontend desacoplado. Establece la URL base del frontend, controla el comportamiento de redirección de rutas del frontend y configura el manejo de URLs de archivos.

Permissions 1
Usar enlace de operación de API

Permite a los usuarios acceder al enlace de operación 'Ver salida de API' en entidades de nodo, que muestra la respuesta JSON de la API para ese nodo.

Hooks 4
hook_trusted_redirect_hosts_alter

Añade las URLs base del frontend configuradas a los hosts de redirección confiables, permitiendo que Drupal redirija al frontend sin advertencias de seguridad.

hook_form_node_form_alter

Altera los formularios de nodos para añadir manejadores de envío personalizados para una integración adecuada con el frontend. Añade el parámetro de consulta ?auth=1 después de guardar nodos y gestiona la redirección de vista previa.

hook_entity_operation

Añade el enlace de operación 'Ver salida de API' a las entidades de nodo para usuarios con el permiso 'use api operation link'.

hook_lupus_decoupled_views_page_alter

Permite alterar el custom element que representa un display de página de Views antes del renderizado.

Troubleshooting 7
Las rutas del frontend no redirigen a la URL del frontend

Asegúrate de que la URL base del frontend esté configurada en /admin/config/system/lupus-decoupled/settings y que la casilla 'Ver contenido en el frontend desacoplado' esté habilitada. También verifica que la variable de entorno DRUPAL_FRONTEND_BASE_URL no esté establecida con un valor vacío.

Errores de CORS cuando el JavaScript del frontend accede a las APIs de Drupal

Asegúrate de que el submódulo lupus_decoupled_cors esté habilitado. Verifica que la URL del frontend esté configurada correctamente, ya que las cabeceras CORS se basan en las URLs base del frontend configuradas.

Imágenes y archivos muestran URLs rotas en el frontend

Verifica que 'Generar respuestas de API de custom-elements con URLs de archivos absolutas' esté habilitado en la configuración. Si usas un CDN o alojamiento de archivos personalizado, configura el ajuste 'file_public_base_url' de Drupal en settings.php.

Los formularios no se envían correctamente desde el frontend

Asegúrate de que el frontend esté configurado para reenviar solicitudes POST al backend. Para Nuxt.js, verifica que el middleware de servidor drupalFormHandler esté correctamente configurado en el conector nuxtjs-drupal-ce.

La vista previa no muestra la página correcta

Habilita lupus_decoupled_responsive_preview y asegúrate de que el procesador de rutas de vista previa esté funcionando. Verifica que el frontend maneje correctamente los parámetros de URL de vista previa.

Las Views no se renderizan como custom elements

Asegúrate de estar usando el tipo de display 'Custom Elements Page' o 'Custom Elements Block', y el plugin de estilo 'Custom Elements'. Verifica que el submódulo lupus_decoupled_views esté habilitado.

La variable de entorno DRUPAL_FRONTEND_BASE_URL no se está usando

La variable de entorno debe establecerse antes de que Drupal se inicie. Verifica que esté exportada en tu entorno de shell o establecida en la configuración de tu servidor web (ej., .htaccess, config de nginx o entorno Docker).

Security Notes 5
  • La configuración de CORS es automática basándose en las URLs del frontend configuradas - evita añadir dominios no confiables a la configuración de URL del frontend.
  • La integración del módulo trusted_redirect asegura que solo los hosts del frontend configurados se permitan como destinos de redirección.
  • Los formularios de autenticación de usuarios mantienen las características de seguridad de Drupal - las credenciales se procesan en el servidor, no en el JavaScript del frontend.
  • El permiso 'use api operation link' solo debe otorgarse a usuarios de confianza que necesiten depurar la salida de la API.
  • Al exponer configuración del sitio mediante lupus_decoupled_site_info, incluye solo valores no sensibles - evita exponer claves de API o credenciales.