feat: add first-party mode for third-party script routing

- Add `scripts.firstParty` config option to route scripts through your domain
- Download scripts at build time and rewrite collection URLs to local paths
- Inject Nitro route rules to proxy requests to original endpoints
- Privacy benefits: hides user IPs, eliminates third-party cookies
- Add `proxy` field to RegistryScript type to mark supported scripts
- Deprecate `bundle` option in favor of unified `firstParty` config
- Add comprehensive unit tests and documentation

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: harlan-zw

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

@@ -0,0 +1,132 @@
+---
+title: First-Party Mode
+description: Route third-party script traffic through your domain for improved privacy and reliability.
+---
+
+## Background
+
+When third-party scripts load directly from external servers, they expose your users' data:
+
+- **IP address exposure** - Every request reveals your users' IP addresses to third parties
+- **Third-party cookies** - External scripts can set cookies for cross-site tracking
+- **Ad blocker interference** - Privacy tools block requests to known tracking domains
+- **Connection overhead** - Extra DNS lookups and TLS handshakes slow page loads
+
+### How First-Party Mode Helps
+
+First-party mode routes all script traffic through your domain:
+
+- **User IPs stay private** - Third parties see your server's IP, not your users'
+- **No third-party cookies** - Requests are same-origin, eliminating cross-site tracking
+- **Works with ad blockers** - Requests appear first-party
+- **Faster loads** - No extra DNS lookups for external domains
+
+## How it Works
+
+When first-party mode is enabled:
+
+1. **Build time**: Scripts are downloaded and URLs are rewritten to local paths (e.g., `https://www.google-analytics.com/g/collect` → `/_scripts/c/ga/g/collect`)
+2. **Runtime**: Nitro route rules proxy requests from local paths back to original endpoints
+
+```
+User Browser → Your Server (/_scripts/c/ga/...) → Google Analytics
+```
+
+Your users never connect directly to third-party servers.
+
+## Usage
+
+### Enable Globally
+
+Enable first-party mode for all supported scripts:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  scripts: {
+    firstParty: true,
+    registry: {
+      googleAnalytics: { id: 'G-XXXXXX' },
+      metaPixel: { id: '123456' },
+    }
+  }
+})
+```
+
+### Custom Paths
+
+Customize the proxy endpoint paths:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  scripts: {
+    firstParty: {
+      collectPrefix: '/_analytics', // Default: /_scripts/c
+    }
+  }
+})
+```
+
+### Opt-out Per Script
+
+Disable first-party routing for a specific script:
+
+```ts
+useScriptGoogleAnalytics({
+  id: 'G-XXXXXX',
+  scriptOptions: {
+    firstParty: false, // Load directly from Google
+  }
+})
+```
+
+## Supported Scripts
+
+First-party mode supports the following scripts:
+
+| Script | Endpoints Routed |
+|--------|------------------|
+| Google Analytics | `www.google.com/g/collect`, `www.google-analytics.com` |
+| Google Tag Manager | `www.googletagmanager.com` |
+| Meta Pixel | `connect.facebook.net`, `www.facebook.com/tr` |
+| TikTok Pixel | `analytics.tiktok.com` |
+| Segment | `api.segment.io`, `cdn.segment.com` |
+| Microsoft Clarity | `www.clarity.ms` |
+| Hotjar | `static.hotjar.com`, `vars.hotjar.com` |
+| X/Twitter Pixel | `analytics.twitter.com`, `t.co` |
+| Snapchat Pixel | `tr.snapchat.com` |
+| Reddit Pixel | `alb.reddit.com` |
+
+## Requirements
+
+First-party mode requires a **server runtime**. It won't work with fully static hosting (e.g., `nuxt generate` to GitHub Pages) because the proxy endpoints need a server to forward requests.
+
+For static deployments, you can still enable first-party mode - scripts will be bundled with rewritten URLs, but you'll need to configure your hosting platform's rewrite rules manually.
+
+### Static Hosting Rewrites
+
+If deploying statically, configure your platform to proxy these paths:
+
+```
+/_scripts/c/ga/* → https://www.google.com/*
+/_scripts/c/gtm/* → https://www.googletagmanager.com/*
+/_scripts/c/meta/* → https://connect.facebook.net/*
+```
+
+## First-Party vs Bundle
+
+First-party mode supersedes the `bundle` option:
+
+| Feature | `bundle: true` | `firstParty: true` |
+|---------|---------------|-------------------|
+| Downloads script at build | ✅ | ✅ |
+| Serves from your domain | ✅ | ✅ |
+| Rewrites collection URLs | ❌ | ✅ |
+| Proxies API requests | ❌ | ✅ |
+| Hides user IPs | ❌ | ✅ |
+| Blocks third-party cookies | ❌ | ✅ |
+
+The `bundle` option only self-hosts the script file. First-party mode also rewrites and proxies all collection/tracking endpoints, providing complete first-party routing.
+
+::callout{type="warning"}
+The `bundle` option is deprecated. Use `firstParty: true` for new projects.
+::

docs/content/docs/1.guides/2.bundling.md docs/content/docs/1.guides/3.bundling.mddocs/content/docs/1.guides/2.bundling.md renamed to docs/content/docs/1.guides/3.bundling.md

@@ -3,6 +3,10 @@ title: Bundling Remote Scripts
 description: Optimize third-party scripts by bundling them with your app.
 ---
 
+::callout{type="warning"}
+The `bundle` option is deprecated in favor of [First-Party Mode](/docs/guides/first-party), which provides the same benefits plus routed collection endpoints for improved privacy. Use `firstParty: true` for new projects.
+::
+
 ## Background
 
 When you use scripts from other sites on your website, you rely on another server to load these scripts. This can slow down your site and raise concerns about safety and privacy.

src/module.ts

@@ -26,8 +26,31 @@ import type {
 } from './runtime/types'
 import { NuxtScriptsCheckScripts } from './plugins/check-scripts'
 import { registerTypeTemplates, templatePlugin, templateTriggerResolver } from './templates'
+import { getAllProxyConfigs, type ProxyConfig } from './proxy-configs'
+
+export interface FirstPartyOptions {
+  /**
+   * Path prefix for serving bundled scripts.
+   * @default '/_scripts'
+   */
+  prefix?: string
+  /**
+   * Path prefix for collection proxy endpoints.
+   * @default '/_scripts/c'
+   */
+  collectPrefix?: string
+}
 
 export interface ModuleOptions {
+  /**
+   * Route third-party scripts through your domain for improved privacy.
+   * When enabled, scripts are downloaded at build time and served from your domain.
+   * Collection endpoints (analytics, pixels) are also routed through your server,
+   * keeping user IPs private and eliminating third-party cookies.
+   *
+   * @default false
+   */
+  firstParty?: boolean | FirstPartyOptions
   /**
    * The registry of supported third-party scripts. Loads the scripts in globally using the default script options.
    */
@@ -147,6 +170,26 @@ export default defineNuxtModule<ModuleOptions>({
       )
     }
 
+    // Handle deprecation of bundle option - migrate to firstParty
+    if (config.defaultScriptOptions?.bundle !== undefined) {
+      logger.warn(
+        '`scripts.defaultScriptOptions.bundle` is deprecated. '
+        + 'Use `scripts.firstParty: true` instead.',
+      )
+      // Migrate: treat bundle as firstParty
+      if (!config.firstParty && config.defaultScriptOptions.bundle) {
+        config.firstParty = true
+      }
+    }
+
+    // Resolve first-party configuration
+    const firstPartyEnabled = !!config.firstParty
+    const firstPartyPrefix = typeof config.firstParty === 'object' ? config.firstParty.prefix : undefined
+    const firstPartyCollectPrefix = typeof config.firstParty === 'object'
+      ? config.firstParty.collectPrefix || '/_scripts/c'
+      : '/_scripts/c'
+    const assetsPrefix = firstPartyPrefix || config.assets?.prefix || '/_scripts'
+
     const composables = [
       'useScript',
       'useScriptEventPage',
@@ -214,6 +257,47 @@ export default defineNuxtModule<ModuleOptions>({
       }
       const { renderedScript } = setupPublicAssetStrategy(config.assets)
 
+      // Inject proxy route rules if first-party mode is enabled
+      if (firstPartyEnabled) {
+        const proxyConfigs = getAllProxyConfigs(firstPartyCollectPrefix)
+        const registryKeys = Object.keys(config.registry || {})
+
+        // Collect routes for all configured registry scripts that support proxying
+        const neededRoutes: Record<string, { proxy: string }> = {}
+        for (const key of registryKeys) {
+          // Find the registry script definition
+          const script = registryScriptsWithImport.find(s => s.import.name === `useScript${key.charAt(0).toUpperCase() + key.slice(1)}`)
+          // Use script's proxy field if defined, otherwise fall back to registry key
+          // If proxy is explicitly false, skip this script entirely
+          const proxyKey = script?.proxy !== false ? (script?.proxy || key) : undefined
+          if (proxyKey) {
+            const proxyConfig = proxyConfigs[proxyKey]
+            if (proxyConfig?.routes) {
+              Object.assign(neededRoutes, proxyConfig.routes)
+            }
+          }
+        }
+
+        // Inject route rules
+        if (Object.keys(neededRoutes).length) {
+          nuxt.options.routeRules = {
+            ...nuxt.options.routeRules,
+            ...neededRoutes,
+          }
+        }
+
+        // Warn for static presets
+        const preset = nuxt.options.nitro?.preset || process.env.NITRO_PRESET || ''
+        const staticPresets = ['static', 'github-pages', 'cloudflare-pages-static']
+        if (staticPresets.includes(preset)) {
+          logger.warn(
+            'Proxy collection endpoints require a server runtime. '
+            + 'Scripts will be bundled but collection requests will not be proxied. '
+            + 'See https://scripts.nuxt.com/docs/guides/proxy for manual platform rewrite configuration.',
+          )
+        }
+      }
+
       const moduleInstallPromises: Map<string, () => Promise<boolean> | undefined> = new Map()
 
       addBuildPlugin(NuxtScriptsCheckScripts(), {
@@ -222,12 +306,14 @@ export default defineNuxtModule<ModuleOptions>({
       addBuildPlugin(NuxtScriptBundleTransformer({
         scripts: registryScriptsWithImport,
         registryConfig: nuxt.options.runtimeConfig.public.scripts as Record<string, any> | undefined,
-        defaultBundle: config.defaultScriptOptions?.bundle,
+        defaultBundle: firstPartyEnabled || config.defaultScriptOptions?.bundle,
+        firstPartyEnabled,
+        firstPartyCollectPrefix,
         moduleDetected(module) {
           if (nuxt.options.dev && module !== '@nuxt/scripts' && !moduleInstallPromises.has(module) && !hasNuxtModule(module))
             moduleInstallPromises.set(module, () => installNuxtModule(module))
         },
-        assetsBaseURL: config.assets?.prefix,
+        assetsBaseURL: assetsPrefix,
         fallbackOnSrcOnBundleFail: config.assets?.fallbackOnSrcOnBundleFail,
         fetchOptions: config.assets?.fetchOptions,
         cacheMaxAge: config.assets?.cacheMaxAge,

src/plugins/transform.ts

@@ -15,6 +15,7 @@ import type { FetchOptions } from 'ofetch'
 import { $fetch } from 'ofetch'
 import { logger } from '../logger'
 import { bundleStorage } from '../assets'
+import { getProxyConfig, rewriteScriptUrls, type ProxyRewrite } from '../proxy-configs'
 import { isJS, isVue } from './util'
 import type { RegistryScript } from '#nuxt-scripts/types'
 
@@ -39,6 +40,14 @@ export interface AssetBundlerTransformerOptions {
    * Used to provide default options to script bundling functions when no arguments are provided
    */
   registryConfig?: Record<string, any>
+  /**
+   * Whether first-party mode is enabled
+   */
+  firstPartyEnabled?: boolean
+  /**
+   * Path prefix for collection proxy endpoints
+   */
+  firstPartyCollectPrefix?: string
   fallbackOnSrcOnBundleFail?: boolean
   fetchOptions?: FetchOptions
   cacheMaxAge?: number
@@ -74,8 +83,9 @@ async function downloadScript(opts: {
   url: string
   filename?: string
   forceDownload?: boolean
+  proxyRewrites?: ProxyRewrite[]
 }, renderedScript: NonNullable<AssetBundlerTransformerOptions['renderedScript']>, fetchOptions?: FetchOptions, cacheMaxAge?: number) {
-  const { src, url, filename, forceDownload } = opts
+  const { src, url, filename, forceDownload, proxyRewrites } = opts
   if (src === url || !filename) {
     return
   }
@@ -84,7 +94,8 @@ async function downloadScript(opts: {
   let res: Buffer | undefined = scriptContent instanceof Error ? undefined : scriptContent?.content
   if (!res) {
     // Use storage to cache the font data between builds
-    const cacheKey = `bundle:${filename}`
+    // Include proxy in cache key to differentiate proxied vs non-proxied versions
+    const cacheKey = proxyRewrites?.length ? `bundle-proxy:${filename}` : `bundle:${filename}`
     const shouldUseCache = !forceDownload && await storage.hasItem(cacheKey) && !(await isCacheExpired(storage, filename, cacheMaxAge))
 
     if (shouldUseCache) {
@@ -111,7 +122,15 @@ async function downloadScript(opts: {
       return Buffer.from(r._data || await r.arrayBuffer())
     })
 
-    await storage.setItemRaw(`bundle:${filename}`, res)
+    // Apply URL rewrites for proxy mode
+    if (proxyRewrites?.length && res) {
+      const content = res.toString('utf-8')
+      const rewritten = rewriteScriptUrls(content, proxyRewrites)
+      res = Buffer.from(rewritten, 'utf-8')
+      logger.debug(`Rewrote ${proxyRewrites.length} URL patterns in ${filename}`)
+    }
+
+    await storage.setItemRaw(cacheKey, res)
     // Save metadata with timestamp for cache expiration
     await storage.setItem(`bundle-meta:${filename}`, {
       timestamp: Date.now(),
@@ -195,6 +214,12 @@ export function NuxtScriptBundleTransformer(options: AssetBundlerTransformerOpti
               const node = _node as SimpleCallExpression
               let scriptSrcNode: Literal & { start: number, end: number } | undefined
               let src: false | string | undefined
+              // Compute registryKey for proxy config lookup
+              let registryKey: string | undefined
+              if (fnName !== 'useScript') {
+                const baseName = fnName.replace(/^useScript/, '')
+                registryKey = baseName.length > 0 ? baseName.charAt(0).toLowerCase() + baseName.slice(1) : undefined
+              }
               if (fnName === 'useScript') {
                 // do easy case first where first argument is a literal
                 if (node.arguments[0]?.type === 'Literal') {
@@ -219,12 +244,8 @@ export function NuxtScriptBundleTransformer(options: AssetBundlerTransformerOpti
                   return
 
                 // integration case
-                // Get registry key from function name (e.g., useScriptGoogleTagManager -> googleTagManager)
-                const baseName = fnName.replace(/^useScript/, '')
-                const registryKey = baseName.length > 0 ? baseName.charAt(0).toLowerCase() + baseName.slice(1) : ''
-
                 // Get registry config for this script
-                const registryConfig = options.registryConfig?.[registryKey] || {}
+                const registryConfig = options.registryConfig?.[registryKey || ''] || {}
 
                 const fnArg0 = {}
 
@@ -331,11 +352,24 @@ export function NuxtScriptBundleTransformer(options: AssetBundlerTransformerOpti
                     canBundle = bundleValue === true || bundleValue === 'force' || String(bundleValue) === 'true'
                     forceDownload = bundleValue === 'force'
                   }
+                  // Check for per-script first-party opt-out (firstParty: false)
+                  // @ts-expect-error untyped
+                  const firstPartyOption = scriptOptions?.value.properties?.find((prop) => {
+                    return prop.type === 'Property' && prop.key?.name === 'firstParty' && prop.value.type === 'Literal'
+                  })
+                  const firstPartyOptOut = firstPartyOption?.value.value === false
                   if (canBundle) {
                     const { url: _url, filename } = normalizeScriptData(src, options.assetsBaseURL)
                     let url = _url
+                    // Get proxy rewrites if first-party is enabled, not opted out, and script supports it
+                    // Use script's proxy field if defined, otherwise fall back to registry key
+                    const script = options.scripts.find(s => s.import.name === fnName)
+                    const proxyConfigKey = script?.proxy !== false ? (script?.proxy || registryKey) : undefined
+                    const proxyRewrites = options.firstPartyEnabled && !firstPartyOptOut && proxyConfigKey && options.firstPartyCollectPrefix
+                      ? getProxyConfig(proxyConfigKey, options.firstPartyCollectPrefix)?.rewrite
+                      : undefined
                     try {
-                      await downloadScript({ src, url, filename, forceDownload }, renderedScript, options.fetchOptions, options.cacheMaxAge)
+                      await downloadScript({ src, url, filename, forceDownload, proxyRewrites }, renderedScript, options.fetchOptions, options.cacheMaxAge)
                     }
                     catch (e: any) {
                       if (options.fallbackOnSrcOnBundleFail) {