Skip to main content
Api

Nuxt Config

Copy for LLMs

registry

  • Type: NuxtConfigScriptRegistry

Register scripts to prepare their proxy routes, types, bundled assets, and composable auto-imports. An entry loads globally only when it has a trigger.

nuxt.config.ts
export default defineNuxtConfig({
  scripts: {
    registry: {
      // Infrastructure only (composable driven)
      googleAnalytics: { id: 'G-XXXXXX' },
      // Infrastructure + global auto-load
      plausibleAnalytics: { domain: 'mysite.com', trigger: 'onNuxtReady' },
      // Opt out of proxy
      posthog: { apiKey: 'phc_xxx', proxy: false },
      // Testing stub (no script loaded, validation skipped)
      clarity: 'mock',
      // Disable a script
      hotjar: false,
    }
  }
})

Per-script capability flags (trigger, proxy, bundle, partytown, privacy) can be set at the top level of the config object alongside the script's input fields. For scripts whose proxy support depends on rewriting a bundled SDK, bundle: false also prevents collection requests from using the proxy. PostHog is the exception: its posthog-js package receives the proxy endpoint through apiHost, so it does not depend on bundling.

Browse the Script Registry for each integration's input and capabilities.

Environment Variables

The module registers each integration's declared environment-backed fields, such as an analytics ID, token, or API key. Override those fields with NUXT_PUBLIC_SCRIPTS_<SCRIPT>_<FIELD> environment variables without declaring matching runtimeConfig keys:

.env
NUXT_PUBLIC_SCRIPTS_GOOGLE_ANALYTICS_ID=G-XXXXXX
NUXT_PUBLIC_SCRIPTS_POSTHOG_API_KEY=phc_xxx
NUXT_PUBLIC_SCRIPTS_CRISP_ID=your-crisp-id

The script must still be present in scripts.registry. Fields that an integration does not declare for environment use still belong in the registry config. These values are exposed through public runtime config, so do not use this mechanism for server-only secrets.

prefix

  • Type: string
  • Default: '/_scripts'

Base path prefix for all script endpoints. Proxy endpoints are served at <prefix>/p/** and bundled assets at <prefix>/assets/**.

nuxt.config.ts
export default defineNuxtConfig({
  scripts: {
    prefix: '/_tracking', // Custom prefix (default: '/_scripts')
  }
})

privacy

  • Type: ProxyPrivacyInput (boolean | ProxyPrivacy)
  • Default: undefined (per-script defaults)

Global privacy override for all proxied scripts. By default, each script uses its own privacy tier declared in the registry. A boolean replaces each per-script default. An object changes only the flags it specifies and preserves the remaining per-script flags.

nuxt.config.ts
export default defineNuxtConfig({
  scripts: {
    // Full anonymization for all proxied traffic
    privacy: true,

    // Or selective override per flag
    privacy: { ip: true },

    // Passthrough (still strips sensitive auth headers)
    privacy: false,
  }
})

See the First-Party Mode Guide for details on privacy tiers and per-script overrides.

proxy.alias

  • Type: boolean | Record<string, string>
  • Default: false

Replaces real hostnames in first-party proxy paths with generated or explicit aliases. true generates an opaque alias for every proxied domain. An object maps each domain to its path segment; unlisted domains remain unchanged.

nuxt.config.ts
export default defineNuxtConfig({
  scripts: {
    proxy: {
      alias: {
        'us.i.posthog.com': 'ph',
      }
    }
  }
})

security

  • Type: false | { secret?: string, autoGenerateSecret?: boolean, pageTokenMaxAge?: number }
  • Default: undefined (the module configures signing after it registers a protected endpoint)

Configures HMAC protection for proxy endpoints that expose server-side API keys or forward arbitrary external resources. The secret falls back to NUXT_SCRIPTS_PROXY_SECRET. In development, the module generates and persists a secret when you enable a signed endpoint without providing one.

Production does not auto-generate a secret. If the module finds a protected endpoint without one, it warns and leaves that endpoint functional but unsigned. URL signing is also unavailable for ssr: false and static Nitro presets because they have no server runtime to verify signatures.

  • security.secret: the HMAC secret
  • security.autoGenerateSecret: whether development may create the secret; defaults to true
  • security.pageTokenMaxAge: client page-token lifetime in seconds; defaults to 3600
  • security: false: disables signing and lets registered endpoints accept unsigned requests

See Proxy Endpoint Security for setup and deployment constraints.

Partytown (Web Worker) Experimental

Load individual scripts in a web worker using Partytown. A registry trigger is still required to generate a global call, but it does not defer the Partytown tag: the current implementation writes that tag into the server-rendered HTML.

nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxtjs/partytown', '@nuxt/scripts'],
  scripts: {
    registry: {
      plausibleAnalytics: { scriptId: 'YOUR_SCRIPT_ID', partytown: true, trigger: 'onNuxtReady' },
    }
  }
})

You must install @nuxtjs/partytown. Nuxt auto-configures the forward array for supported scripts.

Supported Scripts

Nuxt Scripts configures Partytown forwarding for:

  • googleAnalytics, plausibleAnalytics, cloudflareWebAnalytics, umamiAnalytics, matomoAnalytics, mixpanelAnalytics, segment, clarity
  • metaPixel, xPixel, tiktokPixel, snapchatPixel, redditPixel, linkedinInsight, bingUet
  • calendly

Limitations

Partytown is opt-in only for registry scripts with a declared partytown capability. Setting partytown: true on any other registry script is ignored with a development warning. The list above describes eligibility for forwarding, not guaranteed compatibility with the current quick path.

General limitations:

  • The Partytown path preserves only src; it drops other script attributes, skips registry clientInit/beforeInit, ignores trigger timing, and returns no callable proxy. Several integrations in the forwarding list depend on those omitted attributes or initialization hooks, so test the generated tag and vendor traffic before deploying it.
  • segment, mixpanelAnalytics, and bingUet have Partytown forwarding but no collection-proxy capability. If another configured integration activates first-party proxying, Nuxt installs one global resolveUrl that routes every external worker request through the proxy. Requests to domains outside the proxy allowlist then receive a 403. Avoid that mixed configuration, or provide a custom Partytown resolveUrl that leaves those hosts direct.
  • Worker execution can change timing compared with running on the main thread
  • Calls that application code makes on forwarded globals must be listed in Partytown's forward configuration
  • If you provide a custom Partytown resolveUrl, add the Nuxt Scripts proxy routing rules yourself

defaultScriptOptions

  • Type: NuxtUseScriptOptions
  • Default: { trigger: 'onNuxtReady' }

Defaults inherited by each script. The useScript() reference lists the available options.

globals

  • Type: Record<string, NuxtUseScriptInput | [NuxtUseScriptInput, NuxtUseScriptOptionsSerializable]>
  • Default: {}

Scripts registered on every page through useScript().

The Globals guide covers tuples, environment overrides, and $scripts access.

defaultScriptOptions.warmupStrategy

  • Type: false | 'preload' | 'preconnect' | 'dns-prefetch'
  • Default: 'preload' for scripts with onNuxtReady or client triggers; no automatic warmup otherwise

Controls how the browser warms up connections to script origins before the script loads. MDN's speculative loading guide compares the cost and intended use of each resource hint:

  • 'preload' inserts a <link rel="preload"> tag and downloads a script that will load soon.
  • 'preconnect' completes DNS, TCP, and TLS setup for a script that will load later.
  • 'dns-prefetch' resolves only DNS, without downloading the script.
  • false disables warmup entirely. Use when you bundle scripts and serve them from your own domain.

When first-party mode bundles scripts, preconnect and dns-prefetch automatically fall back to false since your origin already serves the script.

enabled

  • Type: boolean
  • Default: true

Set false to disable the Nuxt Scripts module.

debug

  • Type: boolean
  • Default: false

Set true to print debug logs.

assets

  • Type: object
  • Default: { fetchOptions: { retry: 3, retryDelay: 2000, timeout: 15_000 } }

Controls how Nuxt bundles scripts for serving. The only supported strategy is currently 'public'.

The First-Party Mode guide explains the build cache and fallback behavior.

assets.fallbackOnSrcOnBundleFail

  • Type: boolean
  • Default: false

Falls back to the remote src URL when bundling fails. By default, the bundling process stops if the third-party script cannot be downloaded.

assets.fetchOptions

  • Type: object
  • Default: { retry: 3, retryDelay: 2000, timeout: 15_000 }

Options to pass to the fetch function when downloading scripts.

assets.cacheMaxAge

  • Type: number
  • Default: 604800000 (7 days)

Cache duration for bundled scripts in milliseconds. Scripts older than this will be re-downloaded during builds.

assets.integrity

  • Type: boolean | 'sha256' | 'sha384' | 'sha512'
  • Default: false

Generates a Subresource Integrity (SRI) hash for each bundled script and adds integrity with crossorigin="anonymous".

Browsers compare the downloaded script with its declared hash before executing it; see MDN's Subresource Integrity guide.

googleStaticMapsProxy

  • Type: { enabled?: boolean, cacheMaxAge?: number }
  • Default: { enabled: false, cacheMaxAge: 3600 }

Controls the legacy Google Static Maps proxy switch and its response cache duration in seconds. Registering googleMaps also enables the Static Maps and geocoding endpoints. See the Google Maps Static Map API for component usage.

Edit this page
Markdown For LLMs

useScriptEventPage()

React to changes in the current page title or path.

Nuxt App Hooks

Inspect scripts in development or change declared globals at runtime.