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.
| Option | Environment variable | Default | Description |
|---|---|---|---|
url | DRUXT_NODE_PREVIEW_URL | None | The 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. |
consumer | DRUXT_NODE_PREVIEW_CLIENT_ID | None | The client ID of the consumer to register on. |
| None | DRUXT_NODE_PREVIEW_CLIENT_SECRET | None | The consumer's secret. |
label | None | The host of url, such as www.example.com | The target's name in Drupal's Frontend picker. |
token | DRUXT_NODE_PREVIEW_REGISTER_TOKEN | true with backend, otherwise false | Registers a target that reads the preview with a token. See Previews with a token. |
backend | DRUXT_NODE_PREVIEW_REGISTER_BACKEND | None | A Drupal site other than druxt.baseUrl to register on. See Registering on another Drupal site. |
| None | DRUXT_NODE_PREVIEW_REGISTER_SECRET | None | The consumer's secret on the backend site. |
interval | DRUXT_NODE_PREVIEW_REGISTER_INTERVAL | 21600000, 6 hours | The time between registrations, in milliseconds, from 60000 to 2147483647, about 24 days. Keep it shorter than Consumer Node Preview's Inactive limit. |
expiresIn | DRUXT_NODE_PREVIEW_REGISTER_EXPIRES_IN | Twice interval for nuxt dev and nuxt start, otherwise 0 | How 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. |
cleanup | DRUXT_NODE_PREVIEW_REGISTER_CLEANUP | true for nuxt dev and nuxt start, otherwise false | Removes 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:
- Gets a token from
/oauth/tokenon thebackendif there is one, or ondruxt.baseUrl, with Simple OAuth's client credentials grant. - 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, twiceintervalby 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
SIGINTorSIGTERM, 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. ASIGINTorSIGTERMlistener of the site's own gets the signal twice, so make it ignore the second one, or setcleanuptofalse. 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.