Skip to content

Upgrade a Druxt site

Bump every Druxt package together, fix what the release changed, then clear the deprecation warnings the site logs.

Before you start: this guide assumes a working 0.x site. For what the version numbers promise, see Support and versioning.

Install a release as one set

Druxt releases every package together, so move them together. A caret range on a 0.x version stays inside that minor whichever package manager resolves it: ^0.24.0 stops short of 0.25.0, so npm update and yarn upgrade both leave the site where it is. Name each package at its new version instead. First, list the ones your site has:

npm ls --depth=0 | grep druxt

Then install every one of them at once, at the versions the release names. With Yarn, yarn add takes the same list. For 0.25.0, delete the names your site does not use:

npm install druxt@^0.25.0 druxt-site@^0.15.0 \
  druxt-entity@^0.29.0 druxt-router@^0.32.0 druxt-schema@^0.12.0 \
  druxt-views@^0.23.0 druxt-blocks@^0.18.0 druxt-menu@^0.22.0 \
  druxt-breadcrumb@^0.18.0

Nuxt supplies Vue and Vuex, and from 0.25.0 Druxt uses the site's copies rather than installing its own. A second Vue stops Nuxt at startup with a version mismatch, so if package.json lists vue or vuex, remove them:

npm uninstall vue vuex

Breaking changes

Each release's notes list its breaking changes. For 0.25.0:

  1. Module data no longer renders as HTML attributes on wrapper markup: an entity renders <div> where it rendered <div entity="[object Object]" fields="[object Object]">. Find the selectors and tests that matched them with grep -rn '\[entity\]\|\[fields\]\|\[schema\]' assets components layouts pages test and match a class instead. A wrapper still reads the data from $attrs.
  2. Delete any components:extend hook in nuxt.config.js that was added to stop components flickering on first load. Druxt fixes that itself.
  3. The deprecated DruxtField* components are no longer registered. Find them with grep -rn DruxtField components layouts pages, then replace each one as its ledger entry says, or register them again while you do:
// nuxt.config.js
export default {
  druxt: {
    entity: { components: { fields: true } },
  },
}

Clear the deprecation warnings

Deprecated APIs keep working until 2.0.0 removes them, and each use logs a warning that names its replacement. Build and browse the site in development mode:

npm run dev

Browse your site's main pages with the browser console open, and watch the terminal running npm run dev for the server-side render. A warning looks like this:

[druxt] The `hash` argument for `druxt/addResource` has been deprecated,
see https://druxtjs.org/modules/druxt/deprecations#druxtstore-addresource-hash

Each warning links its ledger entry, which states the replacement and the removal version:

Apply each replacement and repeat until nothing is logged.

Opt in to what 0.25.0 adds

  • A server cache keeps Drupal's responses between page requests, for as long as Drupal's Cache-Control allows. It holds the JSON:API index and menus, and with cache.content the content too: Cache Drupal responses on the Nuxt server.
  • druxt.schema.refresh regenerates schemas after a display change in Drupal, with no rebuild: Display schemas.