Make Lookbook script non-blocking to prevent design.gitlab.com outages

Summary

When the Lookbook app is down or slow to respond, it causes design.gitlab.com to hang for all visitors. This is because the Lookbook script is loaded as a blocking <script> tag in the page <head>.

The relevant code in nuxt.config.js (lines 72–76):

script: [
  {
    src: `${LOOKBOOK_URL}/../lookbook-assets/js/lookbook-core.js`,
  },
],

Because this script tag has no async or defer attribute, the browser blocks page rendering until the external Lookbook resource is fetched. If the Lookbook service is unavailable (as happened today), the entire design.gitlab.com site becomes unresponsive.

Proposal

Make the Lookbook script non-blocking by adding async or defer to the script tag:

script: [
  {
    src: `${LOOKBOOK_URL}/../lookbook-assets/js/lookbook-core.js`,
    async: true,
  },
],

This ensures that an outage or slowness in the Lookbook service does not affect the availability of design.gitlab.com for all users.

Impact

  • Current behaviour: If the Lookbook app is down, design.gitlab.com hangs for all visitors.
  • Desired behaviour: If the Lookbook app is down, design.gitlab.com continues to load normally; only Lookbook-specific functionality is degraded.

Context

Identified during a Lookbook outage on 2026-09-01 that caused design.gitlab.com to become unavailable. The Lookbook deployment pipeline was retried as a short-term fix, but the underlying fragility remains.

Chosen approach

Rather than adding async to the <head> entry, the entry is removed entirely and lookbook-core.js is lazy-loaded from components/lookbook_viewer.vue, so only pages with embeds request it.

This is required because lookbook_viewer.vue calls window.Lookbook.initEmbeds() in mounted(), which works today only because the script is blocking. The load must therefore be awaited, with a 5s timeout and a minimal fallback linking to the component's existing inspectUrl.

Note that defer was rejected as an alternative: it still blocks the DOMContentLoaded event, keeping site interactivity coupled to the Lookbook response. The CSP script-src/frame-src entries for the Lookbook origin must be kept.

See the Workplan for the full breakdown.

Edited by Mark Florian