Skip to content

Automatic registration

The frontend can add its own preview target to its Drupal consumer when Nuxt starts. Then nobody copies the URL template into the consumer form by hand. It is off until you turn it on.

Drupal needs Simple OAuth and a consumer set up for it first. See Drupal setup for automatic registration.

// nuxt.config.js
export default {
  druxt: {
    baseUrl: 'https://cms.example.com',
    nodePreview: {
      layouts: ['default', 'preview'],
      register: {
        url: 'https://www.example.com',
        consumer: 'frontend',
      },
    },
  },
}
DRUXT_NODE_PREVIEW_CLIENT_SECRET='<the consumer secret>' npm run start

A shell keeps typed commands in its history. On a shared machine, set the secret in the host's environment settings or a secrets manager instead.

OptionEnvironment variableDefaultDescription
urlDRUXT_NODE_PREVIEW_URLNoneThe frontend's public URL, such as https://www.example.com. Nuxt cannot know it from a build. Add the router base, if the site has one.
consumerDRUXT_NODE_PREVIEW_CLIENT_IDNoneThe client ID of the consumer to register on.
NoneDRUXT_NODE_PREVIEW_CLIENT_SECRETNoneThe consumer's secret.
labelNoneThe host of url, such as www.example.comThe target's name in Drupal's Frontend picker.
tokenDRUXT_NODE_PREVIEW_REGISTER_TOKENtrue with backend, otherwise falseRegisters a target that reads the preview with a token. See Previews with a token.
backendDRUXT_NODE_PREVIEW_REGISTER_BACKENDNoneA Drupal site other than druxt.baseUrl to register on. See Registering on another Drupal site.
NoneDRUXT_NODE_PREVIEW_REGISTER_SECRETNoneThe consumer's secret on the backend site.
intervalDRUXT_NODE_PREVIEW_REGISTER_INTERVAL21600000, 6 hoursThe time between registrations, in milliseconds, from 60000 to 2147483647, about 24 days. Keep it shorter than Consumer Node Preview's Inactive limit.
expiresInDRUXT_NODE_PREVIEW_REGISTER_EXPIRES_INTwice interval for nuxt dev and nuxt start, otherwise 0How long Drupal keeps the target after each registration, in milliseconds, or 0 for no expiry of its own. It must be longer than interval. See Expiry and shutdown.
cleanupDRUXT_NODE_PREVIEW_REGISTER_CLEANUPtrue for nuxt dev and nuxt start, otherwise falseRemoves the target when the server stops cleanly. See Expiry and shutdown.

An environment variable wins over the option in nuxt.config.js. So one config serves local, staging and production, and each host sets its own values. An empty variable counts as unset, so it can't clear an option. To register on druxt.baseUrl by default, leave backend out of nuxt.config.js, and set DRUXT_NODE_PREVIEW_REGISTER_BACKEND only where the frontend registers on another site. register: true takes all of them from the environment. The module reads secrets only from the environment, so keep them out of nuxt.config.js and the repository.

A register secret decides where editors' previews go, and their tokens with them. Anyone who has it can point the consumer's target at a site of their own. So never give it to a build whose authors you don't trust, such as a branch build from a fork.

What happens when Nuxt starts

When Nuxt is ready, in nuxt dev, nuxt build, nuxt generate and nuxt start, the module:

  1. Gets a token from /oauth/token on the backend if there is one, or on druxt.baseUrl, with Simple OAuth's client credentials grant.
  2. Sends its target in a PATCH to Consumer Node Preview's /api/consumer-node-preview/targets. Drupal replaces the target that has the same label, or adds a new one, and records the time. The other targets stay as they are.

The target URL is url, then the path option, then ?vm=[view_mode]&layout=[layout]#[jsonapi_node_preview_path]. Without the layouts option, the URL has no &layout=[layout], and Drupal keeps the consumer's layouts. With the token option, the URL ends in #[jsonapi_node_preview_path];token=[preview_token] instead. With a backend, it holds the full endpoint, #[jsonapi_node_preview];token=[preview_token], because a path would name druxt.baseUrl. A backend turns the token on unless token is false. Then the target holds the full endpoint without a token, and reads with the editor's session. That needs the session and CORS that Paths and full URLs describes.

The module registers when each Nuxt process starts, then every interval while it runs, 6 hours by default. Consumer Node Preview moves a target that stops registering to its Inactive group, after a day by default, and later deletes it. Its Preview tab sets both limits. Keep interval under half the Inactive limit, so a target stays active through a failed attempt, or under a third of it for two, with a margin for how long a request takes. A static site only registers when it builds, so its target goes inactive unless it builds again in time. An inactive target can still be picked.

Expiry and shutdown

A tunnel or a branch build stops, and its target shouldn't stay in the Frontend picker. So a server, nuxt dev or nuxt start, does two things by default:

  • Each registration asks Drupal to keep the target for expiresIn, twice interval by default. A server that stops registering then leaves the picker after that time, however it stopped. Drupal caps the time at its Delete after limit, and the first cron run after the target expires deletes it.
  • When the server gets SIGINT or SIGTERM, as from Ctrl+C or a host stopping it, the module stops registering and removes the target with a DELETE. It waits a few seconds at most, then sends the signal again, so the server stops as it would have. A SIGINT or SIGTERM listener of the site's own gets the signal twice, so make it ignore the second one, or set cleanup to false. A server killed outright can't remove it, so its target goes when it expires.

nuxt build and nuxt generate register once and exit, and a static site's target must stay after its build. So they don't set an expiry or remove the target, unless expiresIn or cleanup says otherwise. A Nuxt server started from your own code counts as a build too, so set both options for it.

nuxt.close() removes the target too. A server of your own that handles SIGINT or SIGTERM and calls process.exit() would stop before the DELETE ends, so await nuxt.close() first. Keep the nuxt that loadNuxt() gives where the handler can reach it. With cleanup on, the module sends the signal again after the removal, so the handler runs twice: let the second call do nothing. A timer stops the server anyway if a close hook hangs:

// server/start.js
let nuxt
let server
let stopping = false

const stop = async () => {
  if (stopping) return
  stopping = true
  setTimeout(() => process.exit(0), 10000).unref()
  await nuxt.close()
  server.close(() => process.exit(0))
}
process.on('SIGINT', stop)
process.on('SIGTERM', stop)

nuxt dev closes and starts again after a config change. The target goes when it closes, and comes back when it starts again.

The expiry and the DELETE need Consumer Node Preview with target expiry. An earlier version ignores the expiry, and answers the DELETE with HTTP 405, so the module warns, and the target stays until Drupal's own limits remove it.

A failure never stops the build or the server. The module shows a warning and Nuxt carries on. A failure before the PATCH leaves the consumer's targets as they were. A PATCH that times out may still have saved the new target, so check the targets as below after a failure. nuxt build and nuxt start both register, so a build without the secret only shows a warning.

The default label is the frontend's host. So local, staging and production each keep their own target on one consumer. Frontends that share a label replace each other's target.

The requests go from Nuxt's server, so they don't need CORS settings. They read Nuxt's top-level axios option first, as Druxt does, then druxt.axios for what it leaves out. Druxt 0.25 deprecates druxt.axios, so set the timeout in axios. Without one, the timeout is 5 seconds:

// nuxt.config.js
export default {
  axios: { timeout: 10000 },
}

On druxt.baseUrl, the requests use the other axios options too. So an Authorization header there, such as Basic auth in front of a staging Drupal, goes with the token request, and Drupal can refuse it with HTTP 401, "Client authentication failed". The requests never follow a redirect, so the secret goes only to the site they name. Use https there, because the token request sends the secret, and the token goes back the same way.

To read the targets back as a site administrator, open this in the browser:

https://cms.example.com/api/consumer-node-preview/targets?consumerId=frontend

Registering on another Drupal site

A frontend can register on a Drupal site other than the one it reads from, such as a branch build that previews content from production. Set backend to that site's URL, and DRUXT_NODE_PREVIEW_REGISTER_SECRET to the consumer's secret there:

DRUXT_NODE_PREVIEW_REGISTER_BACKEND='https://cms.example.com' \
DRUXT_NODE_PREVIEW_REGISTER_SECRET='<the consumer secret>' npm run start

The module never sends DRUXT_NODE_PREVIEW_CLIENT_SECRET to the backend site, so a frontend can't hand its own site's secret to another one by mistake. By default the target reads with a token, because a path would name the wrong site. The module also accepts previews from the backend origin, so editors must open that Drupal site at exactly that origin: the same scheme, host and port. A preview from any other origin is refused. The page fetches from the backend with window.fetch, unless the backend shares an origin with the page or druxt.baseUrl, as The preview request says. Nuxt writes the backend into the page when it builds, so set it for the build as well as for nuxt start. Only registration needs the secret.

The site's axios options are for druxt.baseUrl. So the backend requests get only the timeout, and the proxy in druxt.axios. The global axios defaults and the agents stay with druxt.baseUrl, and so does a client certificate. If the backend site uses a private certificate authority, give Node its certificate with the NODE_EXTRA_CA_CERTS environment variable.

Targets in settings.php

A target for the same frontend can also be in settings.php. Then the Frontend picker shows both, with the registered one under its consumer's label. Once registration works, remove the settings.php target, or keep it as a fallback.

If Consumer Node Preview's default setting names the settings.php target, change or remove it when you remove that target. See Consumer Node Preview's configuration.