Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

@nuxt/scripts

nuxt169kMIT0.10.5TypeScript support: included

Load third-party scripts with better performance, privacy and DX in Nuxt Apps.

readme

nuxt-scripts-social-card

npm version npm downloads License Nuxt Volta

Nuxt Scripts

Better Privacy, Performance, and DX for Third-Party Scripts in Nuxt Apps.

[!IMPORTANT] Nuxt Scripts is in beta, use with caution as some APIs may change.

Features

  • 🪨 Built on top of Unhead
  • 🎁 20+ third-party scripts integrations with fine-grained performance optimizations
  • 🏎️ Performance: Self hosting, advanced script loading triggers, best-practice defaults.
  • 🕵️ Privacy: Defaults to protect end users identity, script consent management APIs.
  • 🪵 DevTools: View your script with their status and see function logs
  • 🚀 0 dependencies, ~2kb minimal runtime

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 more performant, have better privacy and be better DX overall.

🚀 Quick Start

To get started, simply run:

npx nuxi@latest module add scripts

That's it! The Nuxt Scripts module should be downloaded and added to your Nuxt Config modules.

⛰️ Next Steps

Need some inspiration to start using Nuxt Scripts? Try out the following:

  1. 🎉 Make it rain emojis with the Confetti Tutorial.
  2. 📚 Learn about how the Script Loading works.
  3. 🔍 Explore the Script Registry for popular pre-configured third-party scripts.
  4. 🚀 Load other scripts with useScript or Global Scripts.
  5. 🔨 Fine-tune your performance and privacy with Bundling and Consent Management.

⚖️ License

Licensed under the MIT license.

changelog

Changelog

v0.9.7

compare changes

v0.9.6

compare changes

🚀 Enhancements

  • YouTubePlayer: Adjust thumbnail ratio to 640x360 (#310)
  • google-adsense: Add Auto Ads support and improve script injection (#366)
  • useScriptNpm: Support multiple providers with validation (#353)
  • youtube: thumbnailSize prop with fallback support (#376)
  • Add umami analytics to registry (#348)
  • Add Snapchat pixel to registry (#337)

🩹 Fixes

  • nuxtApp.$scripts types (#303)
  • CarbonAds: Avoid duplicate emits (c93bd22)
  • CarbonAds: Unnecessary script type (325cde1)
  • CarbonAds: Missing format prop (#315)
  • Move #nuxt-scripts alias path (2a1ab47)
  • YoutubePlayer,VimeoPlayer: ⚠️ Auto width for responsive design on mobile devices (#341)
  • ⚠️ Drop type dependencies (f545526)
  • Download scripts using $fetch with retries (39c931e)
  • Prefer explicit imports over #imports (a9af35a)
  • Drop third-party-capital (63e78d2)
  • youtube: Default host youtube-nocookie.com (d814c7e)
  • Prefer invisible screen reader loading indicator (ddc88a4)
  • adsense: Use globally configured client in component (3f7e408)

💅 Refactors

  • Remove TPC composable generation (#368)

📖 Documentation

  • Fix typo for google analytics (#317)
  • Fix inconsistent example env keys (#331)
  • Improve incorrect example of using useScriptTriggerElement (#362)

📦 Build

  • Set a resolution for consola (#369)

🏡 Chore

🤖 CI

  • Remove corepack (#372)

⚠️ Breaking Changes

  • YoutubePlayer,VimeoPlayer: ⚠️ Auto width for responsive design on mobile devices (#341)
  • ⚠️ Drop type dependencies (f545526)

❤️ Contributors

v0.9.5

compare changes

🚀 Enhancements

  • googleMaps: Language & region params (#286)
  • Improved script warmup (#302)

🩹 Fixes

  • Avoid warming delayed script src (357d02a)
  • stripe: Prefer @stripe/stripe-js over @types/stripe-v3 (#300)
  • Optional Valibot schema (#287)

📖 Documentation

  • Fix typo/incomplete sentence (#285)

🏡 Chore

❤️ Contributors

v0.9.4

compare changes

🩹 Fixes

  • matomo: Easier cloud config using cloudId (d7e18c4)
  • matomo: Support numeric siteId (299516c)
  • Avoid overriding <link rek="preload" with invalid src (25f1ade)

📖 Documentation

  • Fix docs for disabling scripts in development (#281)

🏡 Chore

❤️ Contributors

v0.9.3

compare changes

🩹 Fixes

  • Use free path for virtual plugin template (8624923)
  • 🐛 Fixed "height" css style property (#275)
  • adsense: Push ad slot once only on dev (#276)

📖 Documentation

  • Update scripts:registry hook example (#271)
  • ✏️ Updated definition for YouTube Player (#273)

🏡 Chore

❤️ Contributors

v0.9.2

compare changes

🩹 Fixes

  • Types for ref triggers (7b3570d)
  • Cache bundled scripts relative to nuxt root (cc5e01b)

🏡 Chore

❤️ Contributors

v0.9.1

compare changes

🩹 Fixes

  • Prefer ref triggers or promise booleans (bacd3de)

🏡 Chore

❤️ Contributors

v0.9.0

compare changes

🚀 Enhancements

  • Allow fallback on bundle fail (#255)

🩹 Fixes

  • adsense: ⚠️ Remove default data-ad-format (#248)
  • Improved bundle: true debug and cache clearing (d269066)
  • metaPixel: Use meta logo instead of facebook logo (#264)
  • Insert script src with app.baseURL (52e1fcb)

🏡 Chore

⚠️ Breaking Changes

  • adsense: ⚠️ Remove default data-ad-format (#248)

❤️ Contributors

v0.8.5

compare changes

🩹 Fixes

  • bundling: Throw error if download fails (#253)
  • Group failed scripts log (#254)
  • YouTube: Broken api types (a00f753)

🏡 Chore

❤️ Contributors

v0.8.4

compare changes

🩹 Fixes

  • ScriptGoogleMaps: Clean up map markers properly (53bb530)

🏡 Chore

❤️ Contributors

v0.8.3

compare changes

🩹 Fixes

  • Do not omit crossorigin from link preload (#241)

🏡 Chore

❤️ Contributors

v0.8.2

compare changes

🚀 Enhancements

  • matomo: Support custom tracker urls (#236)

❤️ Contributors

v0.8.1

compare changes

🩹 Fixes

  • Handle scripts missing src (510d7b9)

📖 Documentation

  • Add learn section and carbon ads (f4de446)

🏡 Chore

❤️ Contributors

v0.8.0

compare changes

v0.7.3

compare changes

v0.7.2

compare changes

🚀 Enhancements

  • Automatically preload and preconnect relevant scripts (a65a5e0)
  • useScriptTriggerElement: Pre-hydration event triggers (#237)
  • googleMaps: Unified styling of static image and map (c85d278)

🩹 Fixes

  • Soft-dependency on Unhead v1.10.1 (4a9fc40)
  • Allow useScript to re-register trigger (9890124)
  • useScriptTriggerElement: Reject promises on scope dispose (7297783)
  • googleAdsense: Broken validation input path (f198a80)

💅 Refactors

  • playground: Avoid deprecated useScript api (0f02696)

📖 Documentation

  • Add coding group end to plausible page (#215)

🏡 Chore

❤️ Contributors

v0.7.1

compare changes

🩹 Fixes

  • Broken type generation (8282d6e)
  • GoogleMaps: Ensure center marker is place when using mapOptions (45e6f24)
  • GoogleMaps: Avoid losing marker reference (406968a)

📖 Documentation

  • Fix broken link (#208)
  • Fix broken link (#211)

🏡 Chore

❤️ Contributors

v0.7.0

compare changes

v0.6.8

compare changes

v0.6.7

compare changes

🚀 Enhancements

  • ⚠️ Improve google maps integration (#191)
  • ⚠️ Unhead 1.10.0 integration (#203)

🩹 Fixes

  • Registry scripts bundling with scriptOptions.bundle (0c7906e)
  • vimeo: ⚠️ Broken player, refactor props (#204)

📖 Documentation

  • Fix broken links (#198)

🏡 Chore

⚠️ Breaking Changes

  • ⚠️ Improve google maps integration (#191)
  • ⚠️ Unhead 1.10.0 integration (#203)
  • vimeo: ⚠️ Broken player, refactor props (#204)

❤️ Contributors

v0.6.6

compare changes

🩹 Fixes

  • tpc: Update TPC and fix GA (#186)

💅 Refactors

  • Avoid module declaration augmentations (b27d4ee)

🏡 Chore

✅ Tests

  • E2e integration tests for ga and gtm (#189)

❤️ Contributors

v0.6.5

compare changes

🚀 Enhancements

  • GA,GTM: Configurable dataLayer name (#163)

🩹 Fixes

  • Fix google analytics category (#156)
  • Use correct google analytics logo (#172)
  • TPC: Use proper script keys (c607d72)
  • TPC: Broken schema integration (ed115d8)
  • Disallow overriding registry key name (2eedd4a)
  • devtools: Support multiple of the same registry scripts (8794d74)
  • ScriptYouTubePlayer: Missing default slot (#180)
  • tpc: Support customizing dataLayer variable (09e3c2f)

📖 Documentation

  • Broken tutorial, put some use into scriptOptions (#155)
  • Fix typo in js-confetti guide (#162)
  • Fix typo in plausible analytics env var example (#161)
  • Mention third-party-capital and aurora for tpc composables (#159)
  • GoogleMaps: Added Places API to requirements of API key (#168)

🏡 Chore

  • Add tsconfig to scripts and remove unused ts-expect-error (#158)
  • Add issue template (669ed2a)
  • Push to discussion (3c88385)
  • Broken devtools when no scripts (c355da4)
  • ci: Add docs link in Issue template (#178)
  • github: Prefer no titles (97437c0)

❤️ Contributors

v0.6.4

compare changes

🚀 Enhancements

  • Support manual script deduping (#148)

🩹 Fixes

  • tpc: Custom feature detection flags (#113)
  • Allow use with npm scripts (dfec3b4)
  • Support explicit scriptInput.src override (be2389f)
  • Safer top level await checks (#149)
  • Prefer module build-time tpc (#153)

💅 Refactors

  • tpc: Write only declaration files (#151)

🏡 Chore

❤️ Contributors

v0.6.3

compare changes

🩹 Fixes

  • tpc: Annotate return type of tpc composables (#141)
  • tpc: Directly push tpc composables into registry (#139)
  • tpc: Use mlly to resolve third-party-capital (#138)

🏡 Chore

❤️ Contributors

v0.6.2

compare changes

🩹 Fixes

  • Broken globals array config parsing (292bd8e)

❤️ Contributors

v0.6.1

compare changes

🏡 Chore

❤️ Contributors

v0.6.0

compare changes

🚀 Enhancements

  • Detect await $script.load() (#117)
  • ⚠️ Convert module config globals to object (#127)
  • ScriptIntercom (fa5ab56)
  • useScriptCrisp and ScriptCrisp (#128)
  • ⚠️ ScriptLemonSqueezy (#130)

🩹 Fixes

  • tpc: Respect script location and action field (#105)
  • docs: Matomo-analytics website url (#118)
  • Generate globals plugin correctly (1594f67)
  • Use object syntax to define NuxtConfigScriptRegistry (#124)
  • Avoid adding plugin if module is disabled (2e4df43)
  • Devtool UI improvements (a8bf500)
  • Make scripts accessible at nuxtApp.$scripts (a41347c)
  • Hook up UI props (993c123)
  • ⚠️ ScriptCarbonAds prefer ready event (d32e0d8)
  • Consistent component error event emits (c9d2b3e)
  • ⚠️ Rename useElementScriptTrigger, useConsentScriptTrigger, useAnalyticsPageEvent (038d891)
  • Properly support array triggers with useScriptTriggerElement (ade64a4)

💅 Refactors

  • tpc: Move tests to AST instead of code snapshots (#99)
  • Refactor import { type foo } to import type { foo } (#108)
  • tpc: Remove augmentWindowTypes (#119)

📖 Documentation

  • readme: Fix links in Next Steps (#102)
  • Add basic contribution guide (#109)
  • Refactor script setup lang="ts" (#116)
  • Fix contributing guide (#122)

🏡 Chore

⚠️ Breaking Changes

  • ⚠️ Convert module config globals to object (#127)
  • ⚠️ ScriptLemonSqueezy (#130)
  • ⚠️ ScriptCarbonAds prefer ready event (d32e0d8)
  • ⚠️ Rename useElementScriptTrigger, useConsentScriptTrigger, useAnalyticsPageEvent (038d891)

❤️ Contributors

v0.5.1

compare changes

🩹 Fixes

❤️ Contributors

v0.5.0

compare changes

🩹 Fixes

❤️ Contributors

v0.4.10

compare changes

v0.4.9

compare changes

v0.4.8

compare changes

🚀 Enhancements

  • tpc: Build-time third-party-capital composables (#81)
  • Clarity (#91)

🩹 Fixes

  • vimeo: Support url prop (#82)
  • Correct scriptBundling return type (#85)

📖 Documentation

  • Update contributors placeholder to chrome aurora (#84)
  • Tweak wording of perf results (#89)
  • Add more detail to billing docs (#88)

🏡 Chore

❤️ Contributors

v0.4.7

compare changes

🚀 Enhancements

  • Carbon ads (#80)

❤️ Contributors

v0.4.6

compare changes

🚀 Enhancements

  • Google adsense (#75)

🩹 Fixes

  • Tree shake registry script src resolvers (f1423d2)
  • useElementScriptTrigger support undefined trigger (c684f6a)

🏡 Chore

❤️ Contributors

v0.4.5

compare changes

🏡 Chore

❤️ Contributors

v0.4.4

compare changes

🩹 Fixes

  • Force useRegistry return type (#73)

📖 Documentation

  • Fix homepage css (#68)
  • Fix homepage ButtonGroup mobile rounded border (#71)

🏡 Chore

❤️ Contributors

v0.4.3

compare changes

🏡 Chore

❤️ Contributors