feat: experimental nuxt/partytown support

docs/content/docs/3.api/1.use-script.md

@@ -71,6 +71,14 @@ export type NuxtUseScriptOptions<T = any> = Omit<UseScriptOptions<T>, 'trigger'>
  * - `false` - Do not bundle the script. (default)
  */
  bundle?: boolean
+ /**
+ * [Experimental] Load the script in a web worker using Partytown.
+ * When enabled, adds `type="text/partytown"` to the script tag.
+ * Requires @nuxtjs/partytown to be installed and configured separately.
+ * Note: Scripts requiring DOM access (GTM, Hotjar, chat widgets) are not compatible.
+ * @see https://partytown.qwik.dev/
+ */
+ partytown?: boolean
  /**
  * Skip any schema validation for the script input. This is useful for loading the script stubs for development without
  * loading the actual script and not getting warnings.

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

@@ -11,6 +11,61 @@ Global registry scripts that should be loaded.
 
 See the [Script Registry](/scripts) for more details.
 
+## `partytown` :badge[Experimental]{color="amber"}
+
+- Type: `(keyof ScriptRegistry)[]`
+- Default: `[]`
+
+Registry scripts to load via [Partytown](https://partytown.qwik.dev/) (web worker).
+
+This is a shorthand for setting `partytown: true` on individual registry scripts. When a script is listed here, it will be loaded with `type="text/partytown"` so Partytown can execute it in a web worker.
+
+::code-group
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+ scripts: {
+ partytown: ['googleAnalytics', 'plausible', 'fathom'],
+ registry: {
+ googleAnalytics: { id: 'G-XXXXX' },
+ plausible: { domain: 'example.com' },
+ fathom: { site: 'XXXXX' }
+ }
+ }
+})
+```
+::
+
+::callout{icon="i-heroicons-exclamation-triangle" color="amber"}
+Requires [`@nuxtjs/partytown`](https://github.com/nuxt-modules/partytown) to be installed. The `forward` array is **automatically configured** for supported registry scripts.
+::
+
+### Supported Scripts
+
+Scripts with auto-forwarding configured:
+- `googleAnalytics`, `plausible`, `fathom`, `umami`, `matomo`, `segment`
+- `metaPixel`, `xPixel`, `tiktokPixel`, `snapchatPixel`, `redditPixel`
+- `cloudflareWebAnalytics`
+
+### Limitations
+
+::callout{icon="i-heroicons-x-circle" color="red"}
+**Incompatible scripts** - The following cannot work with Partytown due to DOM access requirements:
+- **Tag managers**: Google Tag Manager, Adobe Launch
+- **Session replay**: Hotjar, Clarity, FullStory, LogRocket
+- **Chat widgets**: Intercom, Crisp, Drift, HubSpot Chat
+- **Video players**: YouTube, Vimeo embeds
+- **A/B testing**: Optimizely, VWO, Google Optimize
+::
+
+::callout{icon="i-heroicons-exclamation-triangle" color="amber"}
+**General limitations**:
+- Scripts cannot directly access or modify the DOM
+- `document.cookie` access requires additional Partytown configuration
+- Debugging is more complex (code runs in a web worker)
+- Some scripts may have timing differences compared to main thread execution
+- localStorage/sessionStorage access may require forwarding configuration
+::
+
 ## `defaultScriptOptions`
 
 - Type: `NuxtUseScriptOptions`

package.json

@@ -46,7 +46,7 @@
  "prepack": "pnpm dev:prepare && nuxt-module-build build && npm run client:build",
  "dev": "nuxi dev playground",
  "dev:ssl": "nuxi dev playground --https",
- "prepare:fixtures": "nuxi prepare test/fixtures/basic && nuxi prepare test/fixtures/cdn && nuxi prepare test/fixtures/extend-registry",
+ "prepare:fixtures": "nuxi prepare test/fixtures/basic && nuxi prepare test/fixtures/cdn && nuxi prepare test/fixtures/extend-registry && nuxi prepare test/fixtures/partytown",
  "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare playground && pnpm run prepare:fixtures",
  "typecheck": "vue-tsc --noEmit",
  "bump": "bumpp package.json --commit --push --tag",
@@ -124,6 +124,7 @@
  "valibot": "^1.2.0"
  },
  "devDependencies": {
+ "@nuxtjs/partytown": "^2.0.0",
  "@nuxt/devtools-kit": "^3.1.1",
  "@nuxt/devtools-ui-kit": "^3.1.1",
  "@nuxt/eslint-config": "^1.12.1",

src/module.ts

@@ -28,11 +28,37 @@ import type {
 import { NuxtScriptsCheckScripts } from './plugins/check-scripts'
 import { registerTypeTemplates, templatePlugin, templateTriggerResolver } from './templates'
 
+/**
+ * Partytown forward config for registry scripts.
+ * Scripts not listed here are likely incompatible due to DOM access requirements.
+ * @see https://partytown.qwik.dev/forwarding-events
+ */
+const PARTYTOWN_FORWARDS: Record<string, string[]> = {
+ googleAnalytics: ['dataLayer.push', 'gtag'],
+ plausible: ['plausible'],
+ fathom: ['fathom', 'fathom.trackEvent', 'fathom.trackPageview'],
+ umami: ['umami', 'umami.track'],
+ matomo: ['_paq.push'],
+ segment: ['analytics', 'analytics.track', 'analytics.page', 'analytics.identify'],
+ metaPixel: ['fbq'],
+ xPixel: ['twq'],
+ tiktokPixel: ['ttq.track', 'ttq.page', 'ttq.identify'],
+ snapchatPixel: ['snaptr'],
+ redditPixel: ['rdt'],
+ cloudflareWebAnalytics: ['__cfBeacon'],
+}
+
 export interface ModuleOptions {
  /**
  * The registry of supported third-party scripts. Loads the scripts in globally using the default script options.
  */
  registry?: NuxtConfigScriptRegistry
+ /**
+ * Registry scripts to load via Partytown (web worker).
+ * Shorthand for setting `partytown: true` on individual registry scripts.
+ * @example ['googleAnalytics', 'plausible', 'fathom']
+ */
+ partytown?: (keyof NuxtConfigScriptRegistry)[]
  /**
  * Default options for scripts.
  */
@@ -186,6 +212,51 @@ export default defineNuxtModule<ModuleOptions>({
  )
  }
 
+ // Process partytown shorthand - add partytown: true to specified registry scripts
+ // and auto-configure @nuxtjs/partytown forward array
+ if (config.partytown?.length) {
+ config.registry = config.registry || {}
+ const requiredForwards: string[] = []
+
+ for (const scriptKey of config.partytown) {
+ // Collect required forwards for this script
+ const forwards = PARTYTOWN_FORWARDS[scriptKey]
+ if (forwards) {
+ requiredForwards.push(...forwards)
+ }
+ else if (import.meta.dev) {
+ logger.warn(`[partytown] "${scriptKey}" has no known Partytown forwards configured. It may not work correctly or may require manual forward configuration.`)
+ }
+
+ const existing = config.registry[scriptKey]
+ if (Array.isArray(existing)) {
+ // [input, options] format - merge partytown into options
+ existing[1] = { ...existing[1], partytown: true }
+ }
+ else if (existing && typeof existing === 'object' && existing !== true && existing !== 'mock') {
+ // input object format - wrap with partytown option
+ config.registry[scriptKey] = [existing, { partytown: true }] as any
+ }
+ else if (existing === true || existing === 'mock') {
+ // simple enable - convert to array with partytown
+ config.registry[scriptKey] = [{}, { partytown: true }] as any
+ }
+ else {
+ // not configured - add with partytown enabled
+ config.registry[scriptKey] = [{}, { partytown: true }] as any
+ }
+ }
+
+ // Auto-configure @nuxtjs/partytown forward array
+ if (requiredForwards.length && hasNuxtModule('@nuxtjs/partytown')) {
+ const partytownConfig = (nuxt.options as any).partytown || {}
+ const existingForwards = partytownConfig.forward || []
+ const newForwards = [...new Set([...existingForwards, ...requiredForwards])]
+ ;(nuxt.options as any).partytown = { ...partytownConfig, forward: newForwards }
+ logger.info(`[partytown] Auto-configured forwards: ${requiredForwards.join(', ')}`)
+ }
+ }
+
  const composables = [
  'useScript',
  'useScriptEventPage',

src/runtime/composables/useScript.ts

@@ -1,9 +1,9 @@
 import type { UseScriptInput, UseScriptOptions, VueScriptInstance } from '@unhead/vue/scripts'
 import { defu } from 'defu'
 import { useScript as _useScript } from '@unhead/vue/scripts'
-import { reactive } from 'vue'
+import { reactive, ref } from 'vue'
 import type { NuxtDevToolsScriptInstance, NuxtUseScriptOptions, UseFunctionType, UseScriptContext } from '../types'
-import { onNuxtReady, useNuxtApp, useRuntimeConfig, injectHead } from 'nuxt/app'
+import { onNuxtReady, useNuxtApp, useRuntimeConfig, injectHead, useHead } from 'nuxt/app'
 import { logger } from '../logger'
 // @ts-expect-error virtual template
 import { resolveTrigger } from '#build/nuxt-scripts-trigger-resolver'
@@ -22,6 +22,31 @@ export function useScript<T extends Record<symbol | string, any> = Record<symbol
  input = typeof input === 'string' ? { src: input } : input
  options = defu(options, useNuxtScriptRuntimeConfig()?.defaultScriptOptions) as NuxtUseScriptOptions<T>
 
+ // Partytown quick-path: use useHead for SSR rendering
+ // Partytown needs scripts in initial HTML with type="text/partytown"
+ if (options.partytown) {
+ const src = input.src
+ if (!src) {
+ throw new Error('useScript with partytown requires a src')
+ }
+ useHead({
+ script: [{ src, type: 'text/partytown' }],
+ })
+ // Register with nuxtApp.$scripts for DevTools visibility
+ const nuxtApp = useNuxtApp()
+ nuxtApp.$scripts = nuxtApp.$scripts! || reactive({})
+ const status = ref('loaded')
+ const stub = {
+ id: src,
+ status,
+ load: () => Promise.resolve({} as T),
+ remove: () => false,
+ entry: undefined,
+ } as any as UseScriptContext<UseFunctionType<NuxtUseScriptOptions<T>, T>>
+ nuxtApp.$scripts[src] = stub
+ return stub
+ }
+
  // Warn about unsupported bundling for dynamic sources (internal value set by transform)
  if (import.meta.dev && (options.bundle as any) === 'unsupported') {
  console.warn('[Nuxt Scripts] Bundling is not supported for dynamic script sources. Static URLs are required for bundling.')

src/runtime/types.ts

@@ -65,6 +65,13 @@ export type NuxtUseScriptOptions<T extends Record<symbol | string, any> = {}> =
  * Note: Using 'force' may significantly increase build time as scripts will be re-downloaded on every build.
  */
  bundle?: boolean | 'force'
+ /**
+ * Load the script in a web worker using Partytown.
+ * When enabled, adds `type="text/partytown"` to the script tag.
+ * Requires @nuxtjs/partytown to be installed and configured separately.
+ * @see https://partytown.qwik.dev/
+ */
+ partytown?: boolean
  /**
  * Skip any schema validation for the script input. This is useful for loading the script stubs for development without
  * loading the actual script and not getting warnings.

src/templates.ts

@@ -110,23 +110,26 @@ export function templatePlugin(config: Partial<ModuleOptions>, registry: Require
  if (importDefinition) {
  // title case
  imports.unshift(`import { ${importDefinition.import.name} } from '${importDefinition.import.from}'`)
- const args = (typeof c !== 'object' ? {} : c) || {}
  if (c === 'mock') {
-args.scriptOptions = { trigger: 'manual', skipValidation: true }
+inits.push(`const ${k} = ${importDefinition.import.name}({ scriptOptions: { trigger: 'manual', skipValidation: true } })`)
  }
- else if (Array.isArray(c) && c.length === 2 && c[1]?.trigger) {
- const triggerResolved = resolveTriggerForTemplate(c[1].trigger)
+ else if (Array.isArray(c) && c.length === 2) {
+ // [input, options] format - unpack properly
+ const input = c[0] || {}
+ const scriptOptions = { ...c[1] }
+ const triggerResolved = resolveTriggerForTemplate(scriptOptions?.trigger)
  if (triggerResolved) {
- args.scriptOptions = { ...c[1] } as any
- // Store the resolved trigger as a string that will be replaced later
- if (args.scriptOptions) {
- args.scriptOptions.trigger = `__TRIGGER_${triggerResolved}__` as any
- }
+ scriptOptions.trigger = `__TRIGGER_${triggerResolved}__` as any
  if (triggerResolved.includes('useScriptTriggerIdleTimeout')) needsIdleTimeoutImport = true
  if (triggerResolved.includes('useScriptTriggerInteraction')) needsInteractionImport = true
  }
+ const args = { ...input, scriptOptions }
+ inits.push(`const ${k} = ${importDefinition.import.name}(${JSON.stringify(args).replace(/"__TRIGGER_(.*?)__"/g, '$1')})`)
+ }
+ else {
+ const args = (typeof c !== 'object' ? {} : c) || {}
+ inits.push(`const ${k} = ${importDefinition.import.name}(${JSON.stringify(args)})`)
  }
- inits.push(`const ${k} = ${importDefinition.import.name}(${JSON.stringify(args).replace(/"__TRIGGER_(.*?)__"/g, '$1')})`)
  }
  }
  for (const [k, c] of Object.entries(config.globals || {})) {

test/e2e/basic.test.ts

@@ -180,6 +180,16 @@ describe('basic', () => {
  const text = await page.$eval('#script-src', el => el.textContent)
  expect(text).toMatchInlineSnapshot(`"/_scripts/6bEy8slcRmYcRT4E2QbQZ1CMyWw9PpHA7L87BtvSs2U.js"`)
  })
+ it('partytown adds type attribute', async () => {
+ const { page } = await createPage('/partytown')
+ await page.waitForTimeout(500)
+ // verify the script tag has type="text/partytown"
+ const scriptType = await page.evaluate(() => {
+ const script = document.querySelector('script[src="/myScript.js"]')
+ return script?.getAttribute('type')
+ })
+ expect(scriptType).toBe('text/partytown')
+ })
 })
 
 describe('youtube', () => {

test/e2e/partytown.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest'
+import { createResolver } from '@nuxt/kit'
+import { getBrowser, url, waitForHydration, setup } from '@nuxt/test-utils/e2e'
+
+const { resolve } = createResolver(import.meta.url)
+
+await setup({
+ rootDir: resolve('../fixtures/partytown'),
+ browser: true,
+})
+
+describe('partytown integration', () => {
+ it('script tag has type="text/partytown" when partytown option is enabled', async () => {
+ const browser = await getBrowser()
+ const page = await browser.newPage()
+
+ await page.goto(url('/'), { waitUntil: 'networkidle' })
+ await waitForHydration(page, '/')
+
+ // Verify our module correctly sets the type attribute for partytown
+ // Note: Partytown changes type to "text/partytown-x" after processing
+ const scriptType = await page.evaluate(() => {
+ const script = document.querySelector('script[src="/worker-script.js"]')
+ return script?.getAttribute('type')
+ })
+ expect(scriptType?.startsWith('text/partytown')).toBe(true)
+ })
+
+ it('partytown library is loaded and script executes in worker', async () => {
+ const browser = await getBrowser()
+ const page = await browser.newPage()
+
+ // Capture console messages to verify worker execution
+ const consoleLogs: string[] = []
+ page.on('console', msg => consoleLogs.push(msg.text()))
+
+ await page.goto(url('/'), { waitUntil: 'networkidle' })
+ await waitForHydration(page, '/')
+
+ // Wait for partytown to execute scripts
+ await page.waitForTimeout(1000)
+
+ // Verify partytown library is loaded
+ const partytownLib = await page.evaluate(() => {
+ const scripts = Array.from(document.querySelectorAll('script'))
+ return scripts.some(s => s.id === 'partytown' || s.src?.includes('partytown'))
+ })
+ expect(partytownLib).toBe(true)
+
+ // Verify our script executed in the worker (check console log)
+ expect(consoleLogs.some(log => log.includes('Partytown script executing in worker'))).toBe(true)
+ })
+})

test/fixtures/basic/pages/partytown.vue

@@ -0,0 +1,9 @@
+<script setup lang="ts">
+useScript('/myScript.js', { partytown: true })
+</script>
+
+<template>
+ <div id="partytown-test">
+ Partytown test page
+ </div>
+</template>

test/fixtures/partytown/app.vue

@@ -0,0 +1,3 @@
+<template>
+ <NuxtPage />
+</template>

test/fixtures/partytown/nuxt.config.ts

@@ -0,0 +1,14 @@
+import { defineNuxtConfig } from 'nuxt/config'
+
+export default defineNuxtConfig({
+ modules: [
+ '@nuxtjs/partytown',
+ '@nuxt/scripts',
+ ],
+
+ compatibilityDate: '2024-07-05',
+
+ partytown: {
+ debug: true,
+ },
+})

test/fixtures/partytown/package.json

@@ -0,0 +1,5 @@
+{
+ "devDependencies": {
+ "@nuxtjs/partytown": "^2.0.0"
+ }
+}

test/fixtures/partytown/pages/index.vue

@@ -0,0 +1,13 @@
+<script setup lang="ts">
+// Load script in partytown web worker
+useScript('/worker-script.js', { partytown: true })
+</script>
+
+<template>
+ <div>
+ <h1>Partytown Test</h1>
+ <div id="status">
+ Ready
+ </div>
+ </div>
+</template>