This section documents version-specific API changes — prioritize recent major/minor releases.
-
BREAKING: Registry entries no longer auto-load without an explicit trigger property. Build warning fires if config lacks trigger. source
-
BREAKING: PayPal SDK migrated from v5 to v6, changing from callback-based to session-based API. ScriptPayPalButtons now exposes SDK instance via scoped slot, ScriptPayPalMarks removed. source
-
BREAKING: ScriptGoogleMapsPinElement removed entirely. Use #content slot on ScriptGoogleMapsMarker instead. source
-
BREAKING: Google Maps markers and centerMarker props removed from ScriptGoogleMaps. Use child <ScriptGoogleMapsMarker> components declaratively. source
-
BREAKING: Google Maps placeholderOptions, placeholderAttrs, and aboveTheFold props removed. Compose <ScriptGoogleMapsStaticMap> in the #placeholder slot instead. source
-
BREAKING: YouTube Player object-fit default changed from contain to cover. Set placeholder-object-fit="contain" to restore v0 behaviour. source
-
BREAKING: Google Tag Manager onBeforeGtmStart callback now fires for cached scripts. Guard with if (initialized) return to prevent multiple calls. source
-
NEW: useScript().reload() method — re-execute DOM-scanning scripts after SPA navigation. source
-
NEW: SSR social embeds for X (Twitter), Instagram, and Bluesky — fetch embed data server-side, proxy assets through your domain for performance and privacy. source
-
NEW: Partytown web worker support — load third-party scripts off main thread with partytown: true per-script, auto-forwarding supported for 15+ analytics vendors. source
-
NEW: First-party proxy mode with privacy anonymization — reverse proxy requests through your server, anonymise IPs/user agents, block fingerprinting APIs at build time. source
-
NEW: @nuxt/scripts/stats subpath export — audit script privacy ratings, performance impact, cookie analysis, and tracked data types. source
-
NEW: Vendor-native consent controls — consent-aware registry scripts expose typed consent object with update(), grant(), revoke(), and hold() methods. source
-
NEW: YouTube Player aspect ratio control via ratio prop (replaces width/height driven aspect ratio). source
-
NEW: Google Maps declarative component architecture — 11 composable SFC components for markers, shapes, overlays, clustering replacing options-bag API. source
-
NEW: ScriptGoogleMapsStaticMap standalone component — static placeholder now a first-class component with server-side image routing. source
-
NEW: ScriptGoogleMapsGeoJson component — declarative GeoJSON wrapper around google.maps.Data with full event bindings. source
-
NEW: Google Maps ScriptGoogleMapsMarker #content slot — replace default pin with arbitrary HTML/Vue templates. source
-
NEW: Google Maps ScriptGoogleMapsOverlayView — render arbitrary Vue content at map position with full styling control and v-model:open toggling. source
-
NEW: Environment-variable config overrides — auto-populate runtimeConfig.public.scripts from NUXT_PUBLIC_SCRIPTS_* env vars (e.g., NUXT_PUBLIC_SCRIPTS_GOOGLE_ANALYTICS_ID=G-XXXXXX). source
-
NEW: Automatic SRI integrity hash generation — scripts.assets.integrity: 'sha384' generates Subresource Integrity hashes for bundled scripts. source
-
NEW: PostHog Analytics registry script — product analytics with feature flags. source
-
NEW: Google reCAPTCHA v3 registry script — invisible bot protection. source
-
NEW: TikTok Pixel registry script — conversion tracking. source
-
NEW: Google Sign-In registry script — one-tap authentication. source
-
NEW: Rybbit Analytics registry script — privacy-focused open source analytics. source
-
NEW: Databuddy Analytics registry script — lightweight analytics. source
-
NEW: Bing UET registry script — Microsoft Advertising conversion tracking. source
-
NEW: Mixpanel Analytics registry script — product analytics and user tracking. source
-
NEW: Vercel Analytics registry script — Vercel Web Analytics integration. source
-
NEW: Gravatar registry script — avatar service with privacy-preserving proxy. source
-
NEW: LinkedIn Insight Tag registry script — conversion tracking and retargeting for LinkedIn Ads. source
-
NEW: Ahrefs Web Analytics registry script — privacy-first, cookie-less analytics. source
-
NEW: Usercentrics CMP registry script — consent management platform for GDPR/CCPA compliance. source
-
NEW: Calendly registry script — scheduling tool embed widget. source
-
NEW: Build-time debug flag with script-lifecycle tracing — scripts.debug: true in config logs script loading pipeline. source
-
NEW: Env-var overrides for scripts.globals — single build, multi-deploy pattern support via environment variables. source
-
NEW: Consent.default() API + strict GCMv2 validation — Google Consent Mode v2 defaults enforced with runtime validation for GTM and GA. source
-
NEW: TikTok Pixel production hardening — region selection, CAPI deduplication, advanced matching. source
-
Wrap useScript() calls in composables to create singleton instances — allows reuse across components without re-initializing, and centralizes configuration source
-
Use useScriptTriggerConsent() as a binary load gate for cookie banners — scripts remain in awaitingLoad state until accept() is called, simplifying the classic consent flow source
-
Leverage per-script vendor-native consent APIs instead of remapping categories — each script's consent object (e.g. consent.update() for Google Analytics, consent.grant()/consent.revoke() for Meta) matches the vendor's actual API, avoiding lossy projections source
-
Use trigger: 'onNuxtReady' (the default) for idle-loaded scripts — ensures Core Web Vitals remain optimal by deferring third-party script loading until after Nuxt hydration completes and the main thread is idle source
-
Enable first-party mode bundling via bundle: true for performance and privacy — bundled scripts load from your own domain (avoiding DNS lookups and CORS), and proxied requests strip identifying data (IP, user agent, screen dimensions) automatically source
-
Initialize registry scripts in nuxt.config.ts or app.vue with their base config, then call them from components without options — the singleton pattern deduplicates instances and re-initializing in components is unnecessary source
-
Use scriptOptions: { trigger: manual } with element-based triggers (click, visible) for facade components — delays heavyweight third-party loading until explicit user interaction, preventing performance regression source
-
Apply warmupStrategy: 'preconnect' or 'preload' for scripts expected to load within seconds — preload is more aggressive (immediately reserved), preconnect is lighter (DNS + TCP handshake only) source
-
Set mock mode in development config to load a stub script and skip validation — prevents production analytics from triggering during dev, while avoiding console warnings about missing IDs source
-
Use runtime config (runtimeConfig.public.scripts.*) with env var overrides for registry script IDs — keeps secrets out of nuxt.config.ts and enables per-deployment configuration without rebuilds source
-
Store script initialization logic in a wrapper composable instead of calling useScript() directly — enables lifecycle control via onLoaded() for accessing the real script API after it loads, avoiding proxy queueing issues source
-
Override privacy tiers per-script using the privacy object (e.g. privacy: { ip: true, userAgent: true }) — allows fine-grained control over which user data is anonymised before forwarding proxied requests source
-
Prefer vendor-native SPA support (e.g. _iub.cs.api.activateSnippets() for iubenda) over calling reload() on route changes — vendors optimise for their own DOM scanning patterns and avoid unnecessary full script re-execution source
-
Use proxy.alias to replace third-party hostnames with opaque aliases in proxy paths (e.g. us.i.posthog.com → ph) — prevents ad-blockers and network observers from classifying requests by hostname, while the server resolves aliases back to real domains transparently source
