@nuxt/scripts

@nuxt/scripts

Powerful DX improvements for loading third-party scripts in Nuxt.

Features

All the features from Unhead useScript:

• 🦥 Lazy, but fast: defer, fetchpriority: 'low', early connections (preconnect, dns-prefetch)
• ☕ Loading strategies: idle, manual, Promise
• 🪨 Single script instance for your app
• 🎃 Events for SSR scripts: onload, onerror, etc
• 🪝 Proxy API: call the script functions before it's loaded, noop for SSR, stubbable, etc
• 🇹 Fully typed APIs

Plus Nuxt goodies:

• 🕵️ useTrackingScript - Load a tracking script while respecting privacy and consent
• 🪵 DevTools integration - see all your loaded scripts with function logs

Installation

• Install @nuxt/scripts dependency to your project:

pnpm add -D @nuxt/scripts
#
yarn add -D @nuxt/scripts
#
npm install -D @nuxt/scripts

• Add it to your modules section in your nuxt.config:

export default defineNuxtConfig({
  modules: ['@nuxt/scripts']
})

Background

Loading third-party IIFE scripts using useHead composable is easy. However, things start getting more complicated quickly around SSR, lazy loading, and type safety.

Nuxt Scripts was created to solve these issues and more with the goal of making third-party scripts a breeze to use.

Usage

useScript

Please see the useScript documentation.

useTrackingScript

This composables is a wrapper around useScript that respects privacy and cookie consent.

For the script to load you must provide a consent option. This can be promise, ref, or boolean.

const agreedToCookies = ref(false)
useTrackingScript('https://www.google-analytics.com/analytics.js', {
  // will be loaded in when the ref is true
  consent: agreedToCookies
})

If the user has enabled DoNotTrack within their browser, the script will not be loaded, unless explicitly ignoring.

const agreedToCookies = ref(false)
useTrackingScript('https://www.google-analytics.com/analytics.js', {
  ignoreDoNotTrack: true
})

License

Licensed under the MIT license.