{"id":21674390,"url":"https://github.com/drunomics/nuxtjs-drupal-ce","last_synced_at":"2025-06-15T14:36:10.191Z","repository":{"id":38454172,"uuid":"317931208","full_name":"drunomics/nuxtjs-drupal-ce","owner":"drunomics","description":"A Nuxt module to easily connect Drupal via custom elements.","archived":false,"fork":false,"pushed_at":"2025-04-09T08:32:46.000Z","size":3627,"stargazers_count":28,"open_issues_count":9,"forks_count":4,"subscribers_count":2,"default_branch":"2.x","last_synced_at":"2025-04-11T18:57:23.502Z","etag":null,"topics":["drupal","lupus-decoupled","nuxt-module"],"latest_commit_sha":null,"homepage":"https://lupus-decoupled.org/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/drunomics.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-12-02T16:59:01.000Z","updated_at":"2025-04-08T11:33:07.000Z","dependencies_parsed_at":"2022-07-12T17:34:22.698Z","dependency_job_id":"6fb15bc3-a8f3-48cf-9f71-bc26e69d0da3","html_url":"https://github.com/drunomics/nuxtjs-drupal-ce","commit_stats":null,"previous_names":[],"tags_count":72,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drunomics%2Fnuxtjs-drupal-ce","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drunomics%2Fnuxtjs-drupal-ce/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drunomics%2Fnuxtjs-drupal-ce/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drunomics%2Fnuxtjs-drupal-ce/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/drunomics","download_url":"https://codeload.github.com/drunomics/nuxtjs-drupal-ce/tar.gz/refs/heads/2.x","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248514576,"owners_count":21116987,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["drupal","lupus-decoupled","nuxt-module"],"created_at":"2024-11-25T13:44:22.594Z","updated_at":"2025-06-15T14:36:10.176Z","avatar_url":"https://github.com/drunomics.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# nuxtjs-drupal-ce - Nuxt Drupal Custom Elements Connector\n\n[![npm version][npm-version-src]][npm-version-href]\n[![npm downloads][npm-downloads-src]][npm-downloads-href]\n[![ci](https://github.com/drunomics/nuxtjs-drupal-ce/actions/workflows/ci.yml/badge.svg?branch=2.x)](https://github.com/drunomics/nuxtjs-drupal-ce/actions/workflows/ci.yml)\n[![License][license-src]][license-href]\n\n\u003e Connects Nuxt v3 with Drupal via the [Lupus Custom Elements Renderer](https://www.drupal.org/project/lupus_ce_renderer) \n\nPlease refer to https://www.drupal.org/project/lupus_decoupled for more info.\n\nThe 2.x version of the module is compatible with Nuxt 3. For a Nuxt 2 compatible version, please checkout the [1.x version](https://github.com/drunomics/nuxtjs-drupal-ce/tree/1.x)\n\n\n## Pre-requisites\n\n* A [Drupal](https://drupal.org) backend with the \n  [Lupus Custom Elements Renderer](https://www.drupal.org/project/lupus_ce_renderer) \n  module or [Lupus Decoupled Drupal](https://www.drupal.org/project/lupus_decoupled) installed. \n\n## Setup\n\n1. Go to your Nuxt project. If necessary, start a new one:\n\n```bash\nnpx nuxi@latest init \u003cproject-name\u003e\n```\n\n2. Add the `nuxtjs-drupal-ce` module to your Nuxt project\n\n```bash\nnpx nuxi@latest module add drupal-ce\n```\n\n3. Configure `nuxtjs-drupal-ce` in your `nuxt.config.js`\n\n```js\nexport default defineNuxtConfig({\n  modules: [\n    'nuxtjs-drupal-ce',\n  ],\n  drupalCe: {\n    drupalBaseUrl: 'https://your-drupal.example.com',\n    // more options...\n  }\n})\n```\nThe module defaults work well with [Lupus Decoupled Drupal](https://drupal.org/project/lupus_decoupled) - in that case setting the\n`drupalBaseUrl` is enough to get started.\n\n4. Scaffold initial files. After scaffolding, edit them as suiting.\n```bash\nrm -f app.vue \u0026\u0026 npx nuxt-drupal-ce-init\n```\n\n\n## Features\n\n* Fetches pages via the custom elements API provided by the [Lupus Custom Elements Renderer](https://www.drupal.org/project/lupus_ce_renderer) \n* Provides a Nuxt-wildcard route, so all Drupal pages can be rendered via Nuxt.js and vue-router.\n* Integrates page metadata and the page title with Nuxt.\n* Supports breadcrumbs and local tasks (\"Tabs\")\n* Supports authenticated requests. Cookies are passed through to Drupal by default.\n* Supports display of Drupal messages in the frontend.\n* Provides unstyled skeleton components for getting started quickly.\n* Supports fetching and display of Drupal menus via the [Rest menu items](https://www.drupal.org/project/rest_menu_items) module.\n\n\n## Options\n\n- `drupalBaseUrl`: The Drupal base URL, e.g. `https://example.com:8080`. Required.\n\n- `serverDrupalBaseUrl`: Optionally, an alternative drupal base URL to apply in server context.\n\n- `ceApiEndpoint`: The custom elements API endpoint. Defaults to `/ce-api`.\n\n- `fetchOptions`: The default [fetchOptions](https://nuxt.com/docs/api/composables/use-fetch#params)\n   to apply when fetching from the Drupal. Defaults to `{ credentials: 'include' }`.\n\n- `fetchProxyHeaders`: The HTTP request headers to pass through to Drupal, via [useRequestHeaders](https://nuxt.com/docs/api/composables/use-request-headers#userequestheaders). Defaults to `['cookie']`.\n\n- `menuEndpoint`: The menu endpoint pattern used for fetching menus. Defaults to 'api/menu_items/$$$NAME$$$' as fitting\n  to the API provided by the [Rest menu items](https://www.drupal.org/project/rest_menu_items) Drupal module.\n  `$$$NAME$$$` is replaced by the menu name being fetched.\n\n- `menuBaseUrl`: The menu base URL. Defaults to drupalBaseUrl + ceApiEndpoint.\n\n- `addRequestContentFormat`: If specified, the given value is added as `_content_format`\n  URL parameter to requests. Disabled by default.\n\n- `addRequestFormat`: If set to `true`, the `_format=custom_elements` URL parameter\nis added automatically to requests. Defaults to `false`.\n\n- `customErrorPages`: By default, error pages provided by Drupal (e.g. 403, 404 page) are shown,\n  while keeping the right status code. By enabling customErrorPages, the regular Nuxt error\n  pages are shown instead, such that the pages can be customized with Nuxt. Defaults to `false`.\n\n- `useLocalizedMenuEndpoint`: If enabled, the menu endpoint will use a language prefix as configured by [nuxtjs/i18n](https://v8.i18n.nuxtjs.org) module. Defaults to `true`.\n\n- `serverApiProxy`: If enabled, the module will create a Nitro server handler that proxies API requests to Drupal backend. Defaults to `true` for SSR (it's disabled for SSG).\n\n- `passThroughHeaders`: Response headers to pass through from Drupal to the client. Defaults to ['cache-control', 'content-language', 'set-cookie', 'x-drupal-cache', 'x-drupal-dynamic-cache']. Note: This is only available in SSR mode.\n\n- `serverLogLevel`: The log level to use for server-side logging. Defaults to 'info'. Options:\n  - false: The server plugin will not be loaded, keeps the default Nuxt error logging.\n  - 'info': Log all server requests and errors.\n  - 'error': Log only errors.\n\n- `disableFormHandler`: If set to `true`, the form handler middleware will be disabled. Defaults to `false`.\n\n## Overriding options with environment variables\n\nRuntime config values can be overridden with environment variables via `NUXT_PUBLIC_` prefix. Supported runtime overrides:\n\n- `drupalBaseUrl` -\u003e `NUXT_PUBLIC_DRUPAL_CE_DRUPAL_BASE_URL`\n- `serverDrupalBaseUrl` -\u003e `NUXT_PUBLIC_DRUPAL_CE_SERVER_DRUPAL_BASE_URL`\n- `menuBaseUrl` -\u003e `NUXT_PUBLIC_DRUPAL_CE_MENU_BASE_URL`\n- `ceApiEndpoint` -\u003e `NUXT_PUBLIC_DRUPAL_CE_CE_API_ENDPOINT`\n\n## Rendering custom elements\n\nGenerally, custom elements are rendered as [dynamic components](https://nuxt.com/docs/guide/directory-structure/components#dynamic-components) and simply need to be registered as global components.\n\nThe components should be placed in `~/components/global`, refer to the `/playground` directory for an example.\nFor example, for the custom element `node-article-teaser` a global component `node-article-teaser.vue` would be\npicked up for rendering.\n\n### Naming recommendation\n\nWe recommend to name the components lowercase using kebap-case, such that there is a clear 1:1 mapping between\ncustom element names used in the API response and the frontend components. For\nexample use `custom-element-name.vue` instead of `CustomElementName.vue`. Both variants work though.\n\n### Default components (JSON only)\n\nWhen 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.\n\n#### How it works:\n\n1. The module removes the last `-`-separated prefix from the element name.\n2. It then appends a `--default` suffix.\n3. If this modified component exists, it's used for rendering.\n4. If the component is not exiting, the process is repeated.\n\nThis approach allows for generic default components like `drupal-form--default.vue` to be used for specific elements such as `drupal-form-user-login-form.vue`. For customization, developers can simply copy and modify the default component as needed.\n\n#### Example lookup process\n\nWhen 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:\n\n```\nx node-custom-view.vue\nx node-custom-view--default.vue\nx node-custom--default.vue\n✓ node--default.vue\n```\n\n## Form handler middleware\n\nThe form handler middleware is used to process Drupal form submissions by forwarding form-POST\nrequests to Drupal and rendering the response as usual. This option allows you to bypass this\nmiddleware for certain routes or to disable it globally.\n\n### Route level\n\nTo bypass the form handler middleware for certain routes, you can use the `disableFormHandler` option with an array of routes:\n\n```js\nexport default defineNuxtConfig({\n  drupalCe: {\n    disableFormHandler: ['/custom-form'],\n  },\n})\n```\n\n### Global level\n\nTo disable the form handler middleware globally, you can use the `disableFormHandler` option with `true`:\n\n```js\nexport default defineNuxtConfig({\n  drupalCe: {\n    disableFormHandler: true,\n  },\n})\n```\n\n## Deprecated options\n\nThe following options are deprecated and only there for improved backwards compatibility.\n\n- `baseURL`: The base URL of the Drupal /ce-api endpoint, e.g. http://localhost:8888/ce-api.\n   If set, `drupalBaseUrl` is set with the origin of the provided URL.\n\n\n## Error handling\n\nThe module provides a default error handler for the `fetchPage` and `fetchMenu` methods:\n\n- `fetchPage`: Throws an error with the status code and message provided by Drupal.\n- `fetchMenu`: Logs an error message to the console and displays a message in the frontend.\n\n## Customizing error handling\n\nYou have the option to override the default error handlers by using a parameter when calling the `fetch` methods.\n\n- `fetchPage`:\n  ```javascript\n  \u003cscript lang=\"ts\" setup\u003e\n    const { fetchPage } = useDrupalCe()\n\n    function customPageError (error: Record\u003cstring, any\u003e) {\n      throw createError({ statusCode: error.value.statusCode, statusMessage: 'No access.', data: {}, fatal: true })\n    }\n    const page = await fetchPage(useRoute().path, { query: useRoute().query }, customPageError)\n  \u003c/script\u003e\n  ```\n\n- `fetchMenu`:\n  ```javascript\n  \u003cscript lang=\"ts\" setup\u003e\n    const { fetchMenu } = useDrupalCe()\n    const { getMessages } = useDrupalCe()\n    const messages = getMessages()\n\n    function customMenuError (error: Record\u003cstring, any\u003e) {\n      messages.value.push({\n        type: 'error',\n        message: `Menu error: Unavailable. ${error.value.statusCode}`\n      })\n    }\n    const mainMenu = await fetchMenu('main', {}, customMenuError)\n  \u003c/script\u003e\n  ```\n\nNote: The `error` parameter is optional and can be omitted.\n\n## Previous options not supported in 2.x version\n\nThe following options were support in 1.x but got dropped:\n\n- `addVueCompiler`: This is necessary if you want to render custom elements markup on runtime;\n  i.e. use the 'markup' content format. Instead, the vue runtime compiler can be enabled in via\n  Nuxt config, see [here](https://github.com/nuxt/framework/pull/4762).\n\n- `axios`: Options to pass-through to the `drupal-ce`\n  [axios](https://github.com/nuxt-community/axios-module) instance. Use `fetchOptions` instead.\n\n\n## Development\n\n1. Clone this repository.\n2. Install dependencies using `npm install`.\n3. Run `npm run dev:prepare` to generate type stubs.\n4. Use `npm run dev` to start [playground](./playground) in development mode.\n5. Update baseURL setting in Nuxt config with [Lupus Decoupled Drupal](https://www.drupal.org/project/lupus_decoupled) instance URL and append the API-prefix /ce-api, e.g. `https://8080-shaal-drupalpod-8m3z0ms7mb6.ws-eu67.gitpod.io/ce-api`\n\n### Run on StackBlitz\n\n1. [Launch it on StackBlitz](https://stackblitz.com/fork/github/drunomics/nuxtjs-drupal-ce/tree/2.x?startScript=dev:prepare,dev\u0026file=playground/nuxt.config.ts)\n2. Update baseURL setting in Nuxt config with [Lupus Decoupled Drupal](https://www.drupal.org/project/lupus_decoupled) instance URL and append the API-prefix /ce-api, e.g. `https://8080-shaal-drupalpod-8m3z0ms7mb6.ws-eu67.gitpod.io/ce-api`\n\n\n## License\n\n[MIT License](./LICENSE)\n\n## Credits\n\nDevelopment sponsored by [drunomics](https://drunomics.com) \u003chello@drunomics.com\u003e\n\n\u003c!-- Badges --\u003e\n[npm-version-src]: https://img.shields.io/npm/v/nuxtjs-drupal-ce/latest.svg\n[npm-version-href]: https://npmjs.com/package/nuxtjs-drupal-ce\n\n[npm-downloads-src]: https://img.shields.io/npm/dt/nuxtjs-drupal-ce.svg\n[npm-downloads-href]: https://npmjs.com/package/nuxtjs-drupal-ce\n\n[codecov-src]: https://codecov.io/gh/drunomics/nuxt-module-drupal-ce/branch/1.x/graph/badge.svg?token=vX3zknQWZv\n[codecov-href]: https://codecov.io/gh/drunomics/nuxt-module-drupal-ce\n\n[license-src]: https://img.shields.io/npm/l/nuxtjs-drupal-ce.svg\n[license-href]: https://npmjs.com/package/nuxtjs-drupal-ce\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrunomics%2Fnuxtjs-drupal-ce","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdrunomics%2Fnuxtjs-drupal-ce","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrunomics%2Fnuxtjs-drupal-ce/lists"}