nuxt-scripts-skilld

name	nuxt-scripts-skilld
description	ALWAYS use when writing code importing "@nuxt/scripts". Consult for debugging, best practices, or modifying @nuxt/scripts, nuxt/scripts, nuxt scripts, scripts.
metadata	{"version":"1.2.1","generated_by":"Anthropic · Haiku 4.5","generated_at":"2026-06-29T00:00:00.000Z"}

nuxt/scripts @nuxt/scripts@1.2.1

Tags: beta: 1.0.0-beta.32, rc: 1.0.0-rc.11, latest: 1.2.1

References: package.json • Docs • Issues • Discussions • Releases

Search

Use skilld search "query" -p @nuxt/scripts instead of grepping .skilld/ directories. Run skilld search --guide -p @nuxt/scripts for full syntax, filters, and operators.

API Changes

This section documents version-specific API changes for @nuxt/scripts v1.2.1 — prioritise recent major/minor releases and breaking changes that LLMs trained on older data will use incorrectly.

Breaking Changes (v1.0.0 — Major Release)

• BREAKING: Config structure completely reorganised — scripts.registry replaces ad-hoc config, scripts.globals centralises configuration source

• BREAKING: First-party proxy mode config changed — firstParty: { enable: true } replaces older firstParty boolean flag structure source

• BREAKING: Google Maps expose renamed to mapsApi — use const { mapsApi } = await script.load() instead of googleMaps source

• BREAKING: Google Maps top-level center and zoom props deprecated — use initialCenter and initialZoom or declarative ScriptGoogleMapsMarker components source

• BREAKING: PayPal SDK upgraded to v6 — breaking API changes in PayPal instance methods and configuration source

• BREAKING: ScriptGoogleMapsStaticMap now standalone component — no longer a prop on ScriptGoogleMaps, use <ScriptGoogleMapsStaticMap /> directly source

• BREAKING: ScriptGoogleMapsPinElement removed — use <ScriptGoogleMapsMarker> with #content slot for custom marker visuals source

• BREAKING: ScriptGoogleMapsAdvancedMarkerElement consolidated into ScriptGoogleMapsMarker — remove Advanced from component name source

New APIs (v1.0.0 — v1.2.1)

• NEW: useScript().reload() method — re-executes DOM-scanning scripts after SPA navigation for dynamic content updates source

• NEW: ScriptXEmbed and ScriptInstagramEmbed components — server-side SSR embeds with slot-based customisation, replaces third-party embed scripts source

• NEW: ScriptBlueskyEmbed component — Bluesky post embeds with SSR support source

• NEW: @nuxt/scripts/stats subpath export with getScriptStats() — audit script privacy ratings, performance, CWV estimates, and cookie analysis source

• NEW: Vendor-native consent object on script instances — useScriptGoogleTagManager().consent.update(), useScriptMetaPixel().consent.grant(), replaces manual consent tracking source

• NEW: defaultConsent option for consent-aware registry scripts — configure initial consent state before first tracking call source

• NEW: ScriptGoogleMapsGeoJson component — declarative GeoJSON layer with full event bindings, wraps google.maps.Data source

• NEW: ScriptGoogleMapsOverlayView component with #content slot — render Vue components at map coordinates with auto-inheritance of marker position source

• NEW: Partytown web worker support per-script — set partytown: true on registry entries to offload analytics/tracking to a worker thread source

• NEW: NUXT_PUBLIC_SCRIPTS_* environment variables for registry script config — auto-populate runtimeConfig.public.scripts from env without boilerplate source

• NEW: Automatic SRI (Subresource Integrity) hash generation for bundled scripts — set assets: { integrity: 'sha384' } in config source

• NEW: /types-source subpath export — machine-readable type definitions for documentation generators source

• NEW: ScriptVimeoPlayer ratio prop — aspect ratio control matching YouTube Player API source

• NEW: YouTube Player overhaul with isolated instances — multiple players no longer interfere; new ratio prop and cleanup on unmount source

New Registry Scripts (v1.0.0 — v1.1.0)

• NEW: PostHog Analytics (useScriptPostHog()) — product analytics with feature flags source

• NEW: Google reCAPTCHA v3 (useScriptGoogleRecaptcha()) — invisible bot protection source

• NEW: TikTok Pixel (useScriptTikTokPixel()) — conversion tracking with consent API source

• NEW: Google Sign-In (useScriptGoogleSignIn()) — one-tap authentication with helpers source

• NEW: Rybbit Analytics (useScriptRybbit()) — privacy-focused open source analytics source

• NEW: Databuddy Analytics (useScriptDatabuddy()) — lightweight analytics source

• NEW: Bing UET (useScriptBingUet()) — Microsoft Advertising conversion tracking source

• NEW: Mixpanel Analytics (useScriptMixpanel()) — product analytics and user tracking source

• NEW: Vercel Analytics (useScriptVercelAnalytics()) — Vercel Web Analytics integration source

• NEW: Gravatar (useScriptGravatar()) — avatar service with privacy-preserving proxy source

• NEW: LinkedIn Insight Tag (useScriptLinkedInInsight()) — v1.1.0 source

• NEW: Ahrefs Web Analytics (useScriptAhrefs()) — v1.1.0 source

• NEW: Usercentrics CMP (useScriptUsercentrics()) — v1.1.0 source

• NEW: Calendly (useScriptCalendly()) — v1.1.0 source

• NEW: SpeedCurve LUX (useScriptSpeedCurve()) — analytics with LUX snippet vendoring — v1.2.0 source

New Features (v1.1.0 — v1.2.0)

• NEW: Build-time debug flag with script-lifecycle tracing — enable via config to see script execution flow at build time source

• NEW: Environment-variable overrides for scripts.globals — set NUXT_PUBLIC_SCRIPTS_<SCRIPT_KEY>_* for single-build, multi-deploy deployments source

• NEW: Consent.default() with strict GCMv2 validation for useScriptGoogleTagManager() and useScriptGoogleAnalytics() — v1.1.0 source

• NEW: TikTok Pixel production hardening — region selection, CAPI deduplication, advanced matching — v1.1.0 source

• NEW: Runtime disable flag and scripts:globals hook in v1.2.0 — disable scripts at runtime or customise global config source

Deprecated APIs (v1.0.0 — v1.2.0)

• DEPRECATED: Google Maps heatmap component — removed in v1.2.0, no replacement provided source

Also Changed

Google Maps OverlayView class extraction and reactive rendering · YouTube Player aspect ratio support · Multiple a11y fixes across Instagram embed, Vimeo player, YouTube player · Stripe.js SDK version selection · Proxy mode RFC 7230 hop-by-hop header stripping

Best Practices

• Wrap useScript() calls in custom composables to ensure singleton behaviour — each script loads only once globally, and all components share the same instance source

• Use onNuxtReady trigger by default (the default behaviour) — it minimises impact on Core Web Vitals by loading scripts after hydration is complete and the main thread is idle source

• Use useScriptTriggerInteraction() for user-initiated scripts like chat widgets and conditionally-loaded features — prefer explicit events like click over hover to avoid UX issues with event loss source

• Use useScriptTriggerIdleTimeout() for non-critical analytics with a 3–5 second delay — balances analytics completeness against main thread blocking during the critical render window source

• Call onLoaded() instead of relying on proxy when you need the script's actual return value or synchronous access to its API — proxy queues calls before the script loads but doesn't return values source

• Use explicit script.warmup('preload') before manual load when you anticipate the user will need a script — this hints to the browser to download while the app is rendering source

• Prefer global scripts in nuxt.config over scattered useScript() calls when you don't need type-safe API interaction or want to load a script everywhere without composable boilerplate source

• Use trigger: false on registry entries you load via composables rather than globally — this registers proxy routes and types without injecting a <script> tag at build time source

• Gate scripts behind consent with useScriptTriggerConsent() to avoid loading them until the user grants permission — the trigger blocks the script until accept() is called source

• Wire vendor-native consent APIs explicitly for multiple scripts with a single banner — each vendor (Google, Meta, TikTok, Matomo) exposes its own dialect, so write one handler per script rather than trying to abstract source

• Use defaultConsent to set the initial policy before the vendor's first tracking call — this prevents opt-out violations when the script initializes before the user interacts with your banner source

• Provide error fallback and loading slots on Facade Components — minimal default styling is intentional; add your own feedback UI and handle script load failures gracefully source

• Use useScriptEventPage() to track accurate page titles on SPA navigation — Nuxt's head is async, so route change titles are often stale if you poll directly source

• Check each vendor's SPA support before calling reload() — many scripts have their own refresh methods (e.g., _iub.cs.api.activateSnippets() for iubenda) which are more efficient than full reload source