Lupus Decoupled Drupal
Nuxt.jsやその他のJavaScriptフロントエンドでヘッドレスDrupalサイトを構築するためのCustom Elements APIを提供する、すぐに使えるDecoupled Drupalアーキテクチャ。
lupus_decoupled
インストール
composer require 'drupal/lupus_decoupled:^1.4'
composer require 'drupal/lupus_decoupled:^1.1'
概要
Lupus Decoupled Drupalは、/ce-apiでCustom Elements APIを通じてコンテンツを配信できる包括的なDecoupledアーキテクチャソリューションです。Drupalのコンテンツレンダリングを、Nuxt.jsなどのJavaScriptフロントエンドで利用可能なカスタム要素定義を含むJSONレスポンスに変換します。
このモジュールは、フォーム、Views、Block、メニュー、Webform、コンタクトフォーム、ユーザー認証など、Decoupled環境で様々なDrupal機能を処理するためのサブモジュール一式を提供します。フロントエンドルートを設定されたフロントエンドURLに自動的にリダイレクトし、ファイルURLを絶対パスに変換し、CORS設定を処理します。
このアーキテクチャは、Custom Elementsモジュールエコシステム（custom_elements、lupus_ce_renderer）を使用して、Drupalのrender arrayをWebコンポーネントを表す構造化JSONデータに変換します。これにより、コンテンツバックエンドとしてのDrupalと、プレゼンテーション層としてのモダンなJavaScriptフレームワーク間の明確な分離が可能になります。
Features
- DrupalコンテンツをJSONレスポンスに変換する/ce-apiでのCustom Elements APIエンドポイントを提供
- 自動フロントエンドルートリダイレクト - Drupalのノードページを設定されたフロントエンドURLにリダイレクト
- Decoupledフロントエンドでのアセット処理のためにAPIレスポンスで絶対ファイルURLを生成
- フロントエンドJavaScriptがブラウザからDrupal APIにアクセスできるようにするCORS設定
- rest_menu_itemsモジュール経由でDrupalメニューをフロントエンドに配信するメニューAPIエンドポイント統合
- Viewsをカスタム要素としてレンダリングするCustom Elements PageおよびBlockディスプレイプラグインによるViews統合
- プログレッシブフォーム送信のためにDrupalフォームをカスタム要素でラップするフォームレンダリングサポート
- Drupalコンタクトフォームをフロントエンドに配信するコンタクトフォーム統合
- カスタム要素API経由でWebformを公開するWebformモジュール統合
- フロントエンドユーザー認証フローのためのユーザー認証フォームサポート（ログイン、パスワードリセット）
- カスタム要素出力でDrupalのLayout Builderを使用するためのLayout Builder統合
- APIレスポンスにBlockリージョンを追加するBlockレイアウト統合
- 設定可能なサイト設定値を公開する/api/site-infoでのサイト情報RESTリソース
- APIレスポンスでの構造化データのためのSchema Metatag/JSON-LDサポート
- Drupal管理画面でDecoupledフロントエンドをプレビューするためのResponsive Preview統合
- デバッグ用のREST Logモジュールとの API リクエスト/レスポンスロギング統合
- 管理インターフェースでコンポーネントプレビューをレンダリングするためのプレビュープロバイダーシステム
- フロントエンドURL設定のための環境変数サポート（DRUPAL_FRONTEND_BASE_URL）
Use Cases
DrupalサイトのNuxt.jsフロントエンド構築
Lupus Decoupledを使用してDrupalコンテンツをNuxt.jsフロントエンドに配信します。モジュールをインストールし、フロントエンドベースURLを設定し、Nuxtアプリケーションでnuxtjs-drupal-ceコネクターを使用します。/ce-apiエンドポイントがJSONレスポンスを配信し、NuxtアプリがVueコンポーネントとしてレンダリングできます。
Decoupledフロントエンドでのユーザー認証実装
lupus_decoupled_user_formを有効にしてDrupalのログインとパスワードリセットフォームを公開します。フロントエンドはカスタム要素でラップされたサーバーレンダリングされたフォームHTMLを受け取り、Drupalのセキュリティ機能を維持しながらプログレッシブエンハンスメントを可能にします。
Viewsでの一覧ページ作成
lupus_decoupled_viewsを使用してカスタム要素を出力する一覧ページを作成します。ViewにCustom Elements Pageディスプレイを追加し、カスタム要素名を設定すると、View結果が完全なページネーションサポート付きのJSONとして配信されます。
フロントエンドへのWebform公開
lupus_decoupled_webformを有効にして、DrupalのWebformをカスタム要素API経由でアクセス可能にします。ユーザーはフロントエンドでフォームを送信でき、確認メッセージはDrupalのWebformシステムによって処理されます。
マルチフロントエンドアーキテクチャ
lupus_decoupled_ce_api.frontend_base_urlsコンテナパラメータを使用して複数のフロントエンドベースURLを設定します。これにより、単一のDrupalバックエンドが適切なCORS設定で複数のフロントエンドアプリケーションにコンテンツを配信できます。
開発中のAPIレスポンスデバッグ
lupus_decoupled_api_logを有効にしてすべてのAPIリクエストとレスポンスをログに記録します。/admin/config/development/logging/rest_logでREST Logを設定し、/admin/reports/rest_logでログを調査してフロントエンド-バックエンド通信のトラブルシューティングを行います。
フロントエンドへのサイト設定配信
lupus_decoupled_site_infoを使用して、サイト名、スローガン、連絡先メールなどのサイト設定を/api/site-info経由で公開します。drush config:edit lupus_decoupled_site_info.settingsで{config_name}:{config_key}形式で追加の値を設定できます。
DecoupledサイトでのBlockベースレイアウト
lupus_decoupled_blockを有効にしてAPIレスポンスにBlockリージョンを含めます。/admin/structure/blockでBlockを配置すると、対応するルートのAPIレスポンスの「blocks」プロパティに自動的にレンダリングされ含まれます。
Tips
- ddevとGitpodサポートを含む事前設定されたDrupal + Nuxt.jsセットアップでクイックスタートするには、https://github.com/drunomics/lupus-decoupled-projectのプロジェクトテンプレートを使用してください。
- ?auth=1クエリパラメータはノード保存時に自動的に追加され、静的生成されたフロントエンドがすぐに新しいコンテンツを取得できるようにします。
- クリーンなマークアップでフォーム要素をテーマ化するには、不要なDrupal固有のマークアップを削除するlupus-starkテーマ（drupal/lupus_stark）の使用を検討してください。
- APIプレフィックス（/ce-api）は必要に応じてlupus_decoupled_ce_api.api_prefixコンテナパラメータでカスタマイズできます。
- 開発中はlupus_decoupled_api_logを有効にしてAPIリクエストとレスポンスを素早くデバッグできます。
- 複数のフロントエンドを設定する場合は、適切なCORS処理のためにlupus_decoupled_ce_api.frontend_base_urlsに追加のベースURLを追加してください。
- Viewsのカスタム要素名はディスプレイ設定でオーバーライドして、フロントエンドのコンポーネント命名規則に合わせることができます。
- コンテンツ形式（jsonまたはmarkup）はlupus_decoupled_ce_api.content_formatパラメータで設定できます。
- 包括的なドキュメントとチュートリアルについてはhttps://lupus-decoupled.orgを参照してください。
Technical Details
Admin Pages 1
/admin/config/system/lupus-decoupled/settings
DrupalバックエンドとDecoupledフロントエンド間の接続を設定します。フロントエンドベースURLの設定、フロントエンドルートリダイレクト動作の制御、ファイルURL処理の設定を行います。
権限 1
Hooks 4
hook_trusted_redirect_hosts_alter
設定されたフロントエンドベースURLを信頼されたリダイレクトホストに追加し、Drupalがセキュリティ警告なしでフロントエンドにリダイレクトできるようにします。
hook_form_node_form_alter
適切なフロントエンド統合のためにカスタム送信ハンドラーを追加するようにノードフォームを変更します。ノード保存後に?auth=1クエリパラメータを追加し、プレビューリダイレクトを処理します。
hook_entity_operation
「use api operation link」権限を持つユーザーのためにNodeエンティティに「API出力を表示」操作リンクを追加します。
hook_lupus_decoupled_views_page_alter
レンダリング前にViewsページディスプレイを表すカスタム要素を変更できるようにします。
Troubleshooting 7
フロントエンドベースURLが/admin/config/system/lupus-decoupled/settingsで設定されており、「Decoupledフロントエンドでコンテンツを表示」チェックボックスが有効になっていることを確認してください。また、DRUPAL_FRONTEND_BASE_URL環境変数が空の値に設定されていないことを確認してください。
lupus_decoupled_corsサブモジュールが有効になっていることを確認してください。CORSヘッダーは設定されたフロントエンドベースURLに基づいているため、フロントエンドURLが正しく設定されていることを確認してください。
設定で「絶対ファイルURLでカスタム要素APIレスポンスを生成」が有効になっていることを確認してください。CDNまたはカスタムファイルホスティングを使用している場合は、settings.phpでDrupalの「file_public_base_url」設定を設定してください。
フロントエンドがPOSTリクエストをバックエンドに転送するように設定されていることを確認してください。Nuxt.jsの場合、nuxtjs-drupal-ceコネクターでdrupalFormHandlerサーバーミドルウェアが適切に設定されていることを確認してください。
lupus_decoupled_responsive_previewを有効にし、プレビューパスプロセッサーが動作していることを確認してください。フロントエンドがプレビューURLパラメータを正しく処理していることを確認してください。
「Custom Elements Page」または「Custom Elements Block」ディスプレイタイプを使用し、「Custom Elements」スタイルプラグインを使用していることを確認してください。lupus_decoupled_viewsサブモジュールが有効になっていることを確認してください。
環境変数はDrupalがブートストラップする前に設定する必要があります。シェル環境でエクスポートされているか、Webサーバー設定（.htaccess、nginx設定、またはDocker環境など）で設定されていることを確認してください。
Security Notes 5
- CORS設定は設定されたフロントエンドURLに基づいて自動的に行われます - 信頼できないドメインをフロントエンドURL設定に追加しないでください。
- trusted_redirectモジュール統合により、設定されたフロントエンドホストのみがリダイレクト先として許可されます。
- ユーザー認証フォームはDrupalのセキュリティ機能を維持します - 資格情報はフロントエンドJavaScriptではなくサーバー側で処理されます。
- 「use api operation link」権限は、API出力のデバッグが必要な信頼できるユーザーにのみ付与してください。
- lupus_decoupled_site_info経由でサイト設定を公開する場合は、機密でない値のみを含めてください - APIキーや資格情報の公開は避けてください。