feat: improved script warmup

[harlan-zw]

🔗 Linked issue

#294,
#293,

❓ Type of change

• 📖 Documentation (updates to the documentation or readme)
• 🐞 Bug fix (a non-breaking change that fixes an issue)
• 👌 Enhancement (improving an existing functionality)
• ✨ New feature (a non-breaking change that adds functionality)
• 🧹 Chore (updates to the build process or auxiliary tools and libraries)
• ⚠️ Breaking change (fix or feature that would cause existing functionality to change)

📚 Description

Current warmup behavior is a bit crude, this PR aims to improve the stability of it while also exposing end user config for more advance use cases.

Background

Nuxt Scripts will insert relevant warmup link tags to optimize the loading of your scripts. Optimizing
for the quickest load after Nuxt has finished hydrating.

For example if we have a script like so:

useScript('/script.js')

This code will load in /script.js on the onNuxtReady event. As the network may be idle while your Nuxt App is hydrating,
Nuxt Scripts will use this time to warmup the script by inserting a preload tag in the head of the document.

<link rel="preload" href="/script.js" as="script" fetchpriority="low">

The behavior is only applied when we are using the client or onNuxtReady Script Triggers.
To customize the behavior further we can use the warmupStrategy option.

warmupStrategy

The warmupStrategy option can be used to customize the link tag inserted for the script. The option can be a function
that returns an object with the following properties:

• • false - Disable warmup.
• • 'preload' - Preload the script, use when the script is loaded immediately.
• • 'preconnect' or 'dns-prefetch' - Preconnect to the script origin, use when you know a script will be loaded within 10 seconds. Only works when loading a script from a different origin, will fallback to false if the origin is the same.

All of these options can also be passed to a callback function, which can be useful when have a dynamic trigger for the script.

warmup

The warmup function can be called explicitly to add either preconnect or preload link tags for a script. This will only work the first time the function is called.

This can be useful when you know that the script is going to be loaded shortly.

const script = useScript('/video.js', {
  trigger: 'manual'
})
// warmup the script when we think the user may need the script
onVisible(videoContainer, () => {
  script.warmup('preload')
})
// load it in
onClick(videoContainer, () => {
  script.load()
})

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
scripts-docs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Oct 15, 2024 7:21am
scripts-playground	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Oct 15, 2024 7:21am