feat: experimental nuxt/partytown support (#576)

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: harlan-zw

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",

pnpm-lock.yaml

@@ -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/module.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/composables/useScript.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/runtime/types.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 || {})) {

src/templates.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/basic.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)
+  })
+})