refactor!: drop legacy compatibility for v2 (#851)

Author: harlan-zw

.github/workflows/nightly.yml

@@ -26,7 +26,7 @@ jobs:
  - name: Setup Node
 uses: actions/setup-node@v7
 with:
-node-version: lts/*
+node-version: 24
 registry-url: https://registry.npmjs.org/
 cache: pnpm
 

.github/workflows/release.yml

@@ -25,7 +25,7 @@ jobs:
  - name: Setup Node
 uses: actions/setup-node@v7
 with:
-node-version: lts/*
+node-version: 24
 cache: pnpm
 registry-url: https://registry.npmjs.org
 

docs/content/docs/1.getting-started/2.installation.md

@@ -5,8 +5,9 @@ description: Install Nuxt Scripts in an existing Nuxt project.
 
 ## Quick Start
 
-Nuxt Scripts 2 requires Nuxt 4.5.1 or newer and Unhead 3.3.1 or newer. Upgrade an
-existing project before installing:
+Nuxt Scripts 2 requires [Node.js](https://nodejs.org) 24 or newer, Nuxt 4.5.1 or
+newer, including Nuxt 5, and Unhead `>=3.3.1 <4`. Upgrade an existing project
+before installing:
 
 ```bash
 npx nuxi@latest upgrade --force

docs/content/docs/1.guides/2.first-party.md

@@ -60,7 +60,7 @@ export default defineNuxtConfig({
  metaPixel: { id: '123456' },
 
 // Infrastructure + global auto-load
- plausibleAnalytics: { domain: 'mysite.com', trigger: 'onNuxtReady' },
+ plausibleAnalytics: { scriptId: 'YOUR_SCRIPT_ID', trigger: 'onNuxtReady' },
  }
  }
 })
@@ -137,7 +137,7 @@ export default defineNuxtConfig({
  scripts: {
  registry: {
 // Apply all privacy transforms to Plausible instead of its IP-only default
- plausibleAnalytics: { domain: 'mysite.com', privacy: true },
+ plausibleAnalytics: { scriptId: 'YOUR_SCRIPT_ID', privacy: true },
 // IP-only for self-hosted PostHog where you control the data
  posthog: { apiKey: 'phc_xxx', privacy: { ip: true } },
  }
@@ -210,7 +210,7 @@ Disable proxying for a specific script using `proxy: false` in its registry conf
 exportdefaultdefineNuxtConfig({
  scripts: {
  registry: {
- plausibleAnalytics: { domain: 'mysite.com', proxy: false },
+ plausibleAnalytics: { scriptId: 'YOUR_SCRIPT_ID', proxy: false },
  googleAnalytics: { id: 'G-XXXXXX' }, // still proxied
  }
  }

docs/content/docs/3.api/5.nuxt-config.md

@@ -21,7 +21,7 @@ export default defineNuxtConfig({
 // Infrastructure only (composable driven)
  googleAnalytics: { id: 'G-XXXXXX' },
 // Infrastructure + global auto-load
- plausibleAnalytics: { domain: 'mysite.com', trigger: 'onNuxtReady' },
+ plausibleAnalytics: { scriptId: 'YOUR_SCRIPT_ID', trigger: 'onNuxtReady' },
 // Opt out of proxy
  posthog: { apiKey: 'phc_xxx', proxy: false },
 // Testing stub (no script loaded, validation skipped)

docs/content/docs/4.migration-guide/2.v1-to-v2.md

@@ -12,7 +12,8 @@ other components.
 
 | Dependency | Required version |
 |---|---|
-| Nuxt |`>=4.5.1`|
+|[Node.js](https://nodejs.org)|`>=24`|
+| Nuxt |`>=4.5.1`, including Nuxt 5 and Nitro 3 |
 |`@unhead/vue`|`>=3.3.1 <4`|
 |`unhead`|`>=3.3.1 <4`|
 
@@ -22,9 +23,77 @@ Upgrade Nuxt and refresh its locked dependencies before installing v2:
 npx nuxi@latest upgrade --force
 ```
 
+Run the dedicated migration CLI from the project root. Preview its changes first
+if the project has dynamic Nuxt configuration:
+
+```bash
+npx @nuxt/scripts-cli migrate v2 --dry-run
+npx @nuxt/scripts-cli migrate v2
+```
+
+The CLI handles static registry configuration and mechanical API renames. It
+lists dynamic configuration and removed components that need manual follow-up.
+
 The module now stops setup with an actionable error when either Unhead package
 is missing or outside the supported range.
 
+## Registry configuration
+
+Registry entries now accept a flat object, `'mock'`, or `false`. Nuxt Scripts 2
+removes the deprecated `true`, `'proxy-only'`, tuple, nested `scriptOptions`,
+and `reverseProxyIntercept` forms.
+
+```diff
+ scripts: {
+ registry: {
+- googleAnalytics: true,
+- plausibleAnalytics: [{ scriptId: 'YOUR_SCRIPT_ID' }, { proxy: false }],
+- calendly: { scriptOptions: { bundle: false } },
+- posthog: { reverseProxyIntercept: false },
++ googleAnalytics: { trigger: 'onNuxtReady' },
++ plausibleAnalytics: { scriptId: 'YOUR_SCRIPT_ID', proxy: false },
++ calendly: { bundle: false },
++ posthog: { proxy: false },
+ },
+ }
+```
+
+Nuxt Scripts 2 also removes the deprecated top-level `globals` array. Use a
+keyed object so each script has a stable name.
+
+## Google Maps
+
+Nuxt Scripts 2 removes these v1 compatibility aliases and components:
+
+| Removed | Replacement |
+|---|---|
+|`center` and `zoom` props on `<ScriptGoogleMaps>`{lang="html"} |`mapOptions.center` and `mapOptions.zoom`|
+|`googleMaps` template ref key |`mapsApi`|
+|`overlay` template ref key |`overlayView`|
+|`<ScriptGoogleMapsAdvancedMarkerElement>`{lang="html"} |`<ScriptGoogleMapsMarker>`{lang="html"} |
+|`<ScriptGoogleMapsPinElement>`{lang="html"} | The marker `#content` slot |
+|`<ScriptGoogleMapsHeatmapLayer>`{lang="html"} | A maintained heatmap library such as deck.gl |
+
+Google removed `HeatmapLayer` from Maps JavaScript API v3.65, so Nuxt Scripts
+no longer ships a component that depends on it.
+
+Nuxt Scripts 2 removes the legacy `googleStaticMapsProxy` option and the
+billable Google Maps server proxies. Static maps load directly from Google with
+the public browser key. `resolveQueryToLatLng()`{lang="ts"} uses the client Places service.
+Apply website and API restrictions to the key, then configure quota limits.
+
+## Registry APIs
+
+Nuxt Scripts 2 removes these deprecated registry API shapes:
+
+| Removed | Replacement |
+|---|---|
+|`proxy.rybbit.pageview()`{lang="ts"} |`proxy.pageview()`{lang="ts"} |
+|`proxy.ttq('page')`{lang="ts"} |`proxy.ttq.page()`{lang="ts"} |
+|`proxy.ttq('track', ...)`{lang="ts"} |`proxy.ttq.track(...)`{lang="ts"} |
+| Matomo `trackPageView` option |`watch`, which defaults to `true`|
+| Plausible `domain` and `extension` options |`scriptId` and current init options |
+
 ## Consumer scopes
 
 Every `useScript()`{lang="ts"} call now returns an Unhead consumer scope.
@@ -42,7 +111,7 @@ longer necessary.
 
 ## Custom readiness callbacks
 
-The legacy `use` option remains supported. Callback-driven SDKs should migrate
+The `use` option remains supported. Callback-driven SDKs should migrate
 to `resolve({ waitFor })`{lang="ts"}, which automatically removes listeners and
 rejects pending readiness when the script lifecycle ends.
 

docs/content/scripts/google-maps/1.guides/7.billing.md

@@ -11,8 +11,7 @@ Enable only the APIs your implementation uses:
 |---|---|---|
 |[Maps JavaScript API](https://developers.google.com/maps/documentation/javascript/get-api-key)| Yes | Interactive map rendering |
 |[Maps Static API](https://developers.google.com/maps/documentation/maps-static/get-api-key)| Optional | A `<ScriptGoogleMapsStaticMap>`{lang="html"} image, including one placed in the `#placeholder` slot |
-|[Geocoding API](https://developers.google.com/maps/documentation/geocoding/guides-v3/get-api-key)| Optional | Server-side address resolution when you enable the Google Maps registry entry |
-|[Places API (Legacy)](https://developers.google.com/maps/documentation/javascript/legacy/places)| Optional | Client-side `findPlaceFromQuery` fallback when the geocoding proxy is unavailable |
+|[Places API (Legacy)](https://developers.google.com/maps/documentation/javascript/legacy/places)| Optional | Address resolution through `resolveQueryToLatLng()`{lang="ts"} |
 
 The placeholder slot is empty by default, so a normal `<ScriptGoogleMaps>`{lang="html"} does not call the Maps Static API.
 
@@ -24,8 +23,7 @@ Google charges each API by SKU and applies a separate monthly free usage cap to
 |---|---|---:|---:|---|
 | Load the interactive map | Dynamic Maps | 10,000 | $7 | Each time the Maps JavaScript API creates a map |
 | Load a static preview | Static Maps | 10,000 | $2 | Each `<ScriptGoogleMapsStaticMap>`{lang="html"} image request |
-| Resolve an address on the server | Geocoding | 10,000 | $5 | Each uncached Geocoding API request |
-| Resolve an address in the browser | Find Place (legacy) | 5,000 | $17 | When the proxy is unavailable and `resolveQueryToLatLng()`{lang="ts"} falls back to Places |
+| Resolve an address in the browser | Find Place (legacy) | 5,000 | $17 | Each `resolveQueryToLatLng()`{lang="ts"} lookup |
 
 These are USD list prices for the first paid volume tier. Higher-volume tiers, regional pricing, and product changes can alter the total; check the [current Google Maps Platform price list](https://developers.google.com/maps/billing-and-pricing/pricing) before budgeting.
 
@@ -39,17 +37,13 @@ Google replaced the old recurring $200 monthly credit with per-SKU free usage ca
 
 **No default static request:**`<ScriptGoogleMaps>`{lang="html"} leaves its placeholder empty. Add `<ScriptGoogleMapsStaticMap>`{lang="html"} only when a map preview is worth the extra Static Maps event.
 
-**Address resolution:**Registering Google Maps enables a server endpoint that uses the Geocoding API. Without that endpoint, `resolveQueryToLatLng()`{lang="ts"} falls back to the browser's Places library. Coordinates avoid either lookup.
+**Address resolution:**`resolveQueryToLatLng()`{lang="ts"} uses the browser's Places library. Coordinates avoid this lookup.
 
-::callout{color="amber"}
-The current static-map proxy stores and serves Google map images from your server. Google's [Maps Platform FAQ](https://developers.google.com/maps/faq#static_map) says browser applications must load Static Maps images directly from Google and must not store and serve copies. Pass an explicit `api-key` to `<ScriptGoogleMapsStaticMap>`{lang="html"} to bypass the proxy, and review the current [Maps Platform Terms](https://cloud.google.com/maps-platform/terms) for your use case.
-::
-
-Google's terms allow limited Geocoding result caching under specific conditions. The Nuxt endpoint caches upstream geocoding responses for 30 days, so confirm that your use meets the current [service-specific caching terms](https://cloud.google.com/maps-platform/terms/maps-service-terms#6.-geocoding-api).
+**Direct static maps:**`<ScriptGoogleMapsStaticMap>`{lang="html"} loads images directly from Google with a public browser key. Give it a separate key restricted to your website and the Maps Static API, or allow the shared registry key to access the Maps JavaScript API, Places API (Legacy), and Maps Static API.
 
 ## Cost Controls
 
-1.**Use coordinates when you have them.** Pass `center` as `{ lat, lng }` instead of an address to avoid Geocoding or Places requests.
+1.**Use coordinates when you have them.** Pass `center` as `{ lat, lng }` instead of resolving an address through Places.
 
 2.**Keep the default lazy trigger.** Use `trigger="immediate"` only when the map should start loading after hydration instead of waiting for an element interaction.
 
@@ -79,4 +73,4 @@ For 100,000 monthly page views under the July 2026 global list prices:
 | Static preview on every view, no interaction | $180 |
 | Static preview on every view and 20% interact | $250 |
 
-These examples apply each SKU's free usage cap and exclude geocoding, Places requests, taxes, negotiated discounts, and other projects on the same billing account.
+These examples apply each SKU's free usage cap and exclude Places requests, taxes, negotiated discounts, and other projects on the same billing account.

docs/content/scripts/google-maps/2.api/1.script-google-maps.md

@@ -21,28 +21,13 @@ The default events are `mouseenter`, `mouseover`, and `mousedown`.
 
 See the [Facade Component API](/docs/guides/facade-components#facade-components-api) for all props, events, and slots.
 
-::tip
-**Deprecated:** the top-level `center` and `zoom` props are now deprecated. Pass them via `mapOptions` instead. The legacy props still work and emit a dev-mode warning when used. `mapOptions.center` and `mapOptions.zoom` take precedence when both are set.
-
-```vue
-<template>
- <!-- Before (deprecated) -->
- <ScriptGoogleMaps :center="{ lat, lng }" :zoom="12" />
-
- <!-- After -->
- <ScriptGoogleMaps :map-options="{ center: { lat, lng }, zoom: 12 }" />
-</template>
-```
-::
-
 ## Template Ref API
 
 Access the basic Google Maps instances via a template ref. The exposed object contains:
 
 | Property | Type | Description |
 |----------|------|-------------|
 |`mapsApi`|`typeof google.maps \| undefined`{lang="html"} | The core Maps API namespace (`google.maps`). |
-|`googleMaps`|`typeof google.maps \| undefined`{lang="html"} |**Deprecated.** Alias for `mapsApi`; emits a dev-mode warning. Slated for removal in a future major version. |
 |`map`|`google.maps.Map \| undefined`{lang="html"} | The map instance. |
 |`resolveQueryToLatLng`|`(query) => Promise<google.maps.LatLng \| google.maps.LatLngLiteral \| undefined>`{lang="html"} | Geocode an address to coordinates. The promise rejects when Google returns no location or the request fails. |
 |`importLibrary`|`(name) => Promise<Library>`{lang="html"} | Load additional Google Maps libraries at runtime. |
@@ -66,7 +51,7 @@ async function flyToSydney() {
 </template>
 ```
 
-Vue unwraps the exposed refs when you access them through a component template ref, as in the example above. The `@ready` payload uses the raw exposed object, so its `mapsApi`, `googleMaps`, and `map` properties are `ShallowRef`s.
+Vue unwraps the exposed refs when you access them through a component template ref, as in the example above. The `@ready` payload uses the raw exposed object, so its `mapsApi` and `map` properties are `ShallowRef`s.
 
 ## Map events