nuxtjs-drupal-ce - Nuxt.js Drupal Custom Elements Connector

Connects Nuxt v3 with Drupal via the Lupus Custom Elements Renderer

Please refer to https://www.drupal.org/project/lupus_decoupled for more info.

The 2.x version of the module is compatible with Nuxt 3. For a Nuxt 2 compatible version, please checkout the 1.x version

Pre-requisites

A Drupal backend with the Lupus Custom Elements Renderer module or Lupus Decoupled Drupal installed.

Setup

Add nuxtjs-drupal-ce dependency to your Nuxt project

yarn add nuxtjs-drupal-ce@beta # or npm install nuxtjs-drupal-ce@beta

Add nuxtjs-drupal-ce to the modules section of nuxt.config.js

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

The module defaults work well with Lupus Decoupled Drupal, so setting the baseURL is usually enough.

Get started quickly by scaffolding initial files:

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

Features

Fetches pages via the custom elements API provided by the Lupus Custom Elements Renderer
Provides a Nuxt-wildcard route, so all Drupal pages can be rendered via Nuxt.js and vue-router.
Integrates page metadata and the page title with Nuxt.
Supports breadcrumbs and local tasks ("Tabs")
Supports authenticated requests. Cookies are passed through to Drupal by default.
Supports display of Drupal messages in the frontend.
Provides unstyled skeleton components for getting started quickly.
Supports fetching and display of Drupal menus via the Rest menu items module.

Options

baseURL: The Drupal base URL. Defaults to the DRUPAL_BASE_URL environment variable if provided, otherwise to http://localhost:8888.
fetchOptions: The default fetchOptions to apply when fetching from the Drupal. Defaults to { credentials: 'include' }.
fetchProxyHeaders: The HTTP request headers to pass through to Drupal, via useRequestHeaders. Defaults to ['cookie'].
menuEndpoint: The menu endpoint pattern used for fetching menus. Defaults to 'api/menu_items/$$$NAME$$$' as fitting to the API provided by the Rest menu items Drupal module. $$$NAME$$$ is replaced by the menu name being fetched.
addRequestContentFormat: If specified, the given value is added as _content_format URL parameter to requests. Disabled by default.
addRequestFormat: If set to true, the _format=custom_elements URL parameter is added automatically to requests. Defaults to false.
customErrorPages: By default, error pages provided by Drupal (e.g. 403, 404 page) are shown, while keeping the right status code. By enabling customErrorPages, the regular Nuxt error pages are shown instead, such that the pages can be customized with Nuxt. Defaults to false.
useLocalizedMenuEndpoint: If enabled, the menu endpoint will use a language prefix as configured by nuxtjs/i18n module. Defaults to true.

Error handling

The module provides a default error handler for the fetchPage and fetchMenu methods:

fetchPage: Throws an error with the status code and message provided by Drupal.
fetchMenu: Logs an error message to the console and displays a message in the frontend.

Customizing error handling

You have the option to override the default error handlers by using a parameter when calling the fetch methods.

fetchPage:

<script lang="ts" setup>
  const { fetchPage } = useDrupalCe()

  function customPageError (error: Record<string, any>) {
    throw createError({ statusCode: error.value.statusCode, statusMessage: 'No access.', data: {}, fatal: true })
  }
  const page = await fetchPage(useRoute().path, { query: useRoute().query }, customPageError)
</script>

fetchMenu:

<script lang="ts" setup>
  const { fetchMenu } = useDrupalCe()
  const { getMessages } = useDrupalCe()
  const messages = getMessages()

  function customMenuError (error: Record<string, any>) {
    messages.value.push({
      type: 'error',
      message: `Menu error: Unavailable. ${error.value.statusCode}`
    })
  }
  const mainMenu = await fetchMenu('main', {}, customMenuError)
</script>

Note: The error parameter is optional and can be omitted.

Previous options not supported in 2.x version

The following options were support in 1.x but got dropped:

addVueCompiler: This is necessary if you want to render custom elements markup on runtime; i.e. use the 'markup' content format. If you need this, you may find a solution in this GitHub issue.
axios: Options to pass-through to the drupal-ce axios instance. Use fetchOptions instead.
useProxy: If set to dev-only and nuxt is in dev-mode, the module automatically configures /api to the Drupal backend via @nuxtjs/proxy and uses it instead of the Drupal backend, such that there are no CORS issues. Other values supported are always or false. Note: When using always the module must be added to the nuxt modules section instead of the buildModules section.

Development

Clone this repository.
Install dependencies using npm install.
Run npm run dev:prepare to generate type stubs.
Use npm run dev to start playground in development mode.
Update baseURL setting in Nuxt config with Lupus Decoupled Drupal instance URL and append the API-prefix /ce-api, e.g. https://8080-shaal-drupalpod-8m3z0ms7mb6.ws-eu67.gitpod.io/ce-api

Run on StackBlitz

Launch it on StackBlitz
Update baseURL setting in Nuxt config with Lupus Decoupled Drupal instance URL and append the API-prefix /ce-api, e.g. https://8080-shaal-drupalpod-8m3z0ms7mb6.ws-eu67.gitpod.io/ce-api

License

MIT License

Credits

Development sponsored by drunomics hello@drunomics.com

drunomics / nuxtjs-drupal-ce