|
| 1 | +--- |
| 2 | +title: v1 to v2 |
| 3 | +description: Migration guide for upgrading from Nuxt Scripts v1.x to v2.0. |
| 4 | +--- |
| 5 | + |
| 6 | +Nuxt Scripts 2 moves script ownership and SDK readiness onto the lifecycle APIs |
| 7 | +introduced in Unhead 3.3.1. This removes component callbacks and trigger listeners |
| 8 | +as soon as their consumer unmounts, without tearing down a script still used by |
| 9 | +other components. |
| 10 | + |
| 11 | +## Requirements |
| 12 | + |
| 13 | +| Dependency | Required version | |
| 14 | +|---|---| |
| 15 | +| Nuxt |`>=4.5.1`| |
| 16 | +|`@unhead/vue`|`>=3.3.1 <4`| |
| 17 | +|`unhead`|`>=3.3.1 <4`| |
| 18 | + |
| 19 | +Upgrade Nuxt and refresh its locked dependencies before installing v2: |
| 20 | + |
| 21 | +```bash |
| 22 | +npx nuxi@latest upgrade --force |
| 23 | +``` |
| 24 | + |
| 25 | +The module now stops setup with an actionable error when either Unhead package |
| 26 | +is missing or outside the supported range. |
| 27 | + |
| 28 | +## Consumer scopes |
| 29 | + |
| 30 | +Every `useScript()`{lang="ts"} call now returns an Unhead consumer scope. |
| 31 | +Component unmount automatically releases callbacks and trigger listeners owned |
| 32 | +by that call. |
| 33 | + |
| 34 | +-`dispose()`{lang="ts"} releases only the current consumer. |
| 35 | +-`signal` aborts when you dispose that consumer or any caller removes the shared script. |
| 36 | +-`script` points to the shared script instance. |
| 37 | +-`remove()`{lang="ts"} still removes the shared script for all consumers. |
| 38 | + |
| 39 | +If application code used `remove()`{lang="ts"} as component cleanup, switch it |
| 40 | +to `dispose()`{lang="ts"}. In Vue components, manual cleanup is normally no |
| 41 | +longer necessary. |
| 42 | + |
| 43 | +## Custom readiness callbacks |
| 44 | + |
| 45 | +The legacy `use` option remains supported. Callback-driven SDKs should migrate |
| 46 | +to `resolve({ waitFor })`{lang="ts"}, which automatically removes listeners and |
| 47 | +rejects pending readiness when the script lifecycle ends. |
| 48 | + |
| 49 | +```diff |
| 50 | + const script = useScript('https://example.com/sdk.js', { |
| 51 | +- use: () => readyPromise.then(() => window.example), |
| 52 | ++ resolve: ({ waitFor }) => waitFor((resolve) => { |
| 53 | ++ window.onExampleReady = () => resolve(window.example) |
| 54 | ++ return () => delete window.onExampleReady |
| 55 | ++ }), |
| 56 | + }) |
| 57 | +``` |
| 58 | + |
| 59 | +The bundled Google Maps, YouTube Player, Crisp, and Usercentrics integrations |
| 60 | +now use this API. `load()`{lang="ts"} resolves only after each vendor's concrete |
| 61 | +SDK API is ready. |
| 62 | + |
| 63 | +## Script triggers |
| 64 | + |
| 65 | +Nuxt's idle-timeout, interaction, and service-worker helpers now return Unhead |
| 66 | +trigger functions. Existing `scriptOptions.trigger` usage is unchanged. Custom |
| 67 | +trigger functions may return a cleanup callback; Unhead calls it when the |
| 68 | +consumer scope is disposed. |
0 commit comments