Module options
Module options live under mixpanel in nuxt.config.ts. See Configuration for setup examples.
Client
client.enabled
Type: boolean
Default: true
Enable browser tracking. When false, useMixpanel() returns an inactive client.
client.token
Type: string
Default: ''
Project token passed to the browser SDK. The server token is not used as a fallback.
client.pageviewStrategy
Type: 'router' | 'native'
Default: 'router'
Selects the Nuxt Router integration ('router') or Mixpanel native tracking ('native') for automatic pageviews. Both strategies use client.config.track_pageview or client.config.autocapture.pageview to enable tracking and select which URL changes to record.
An invalid build-time value throws. An invalid runtime value logs a warning and falls back to 'router'.
See Pageview strategy for the differences between strategies.
client.config
Type: JSON-compatible browser SDK options
Default: {} when no configuration file is used
Options passed to browser initialization. Inline values follow the serialization rules.
Use defineMixpanelClientConfig in a configuration file for callbacks and regular expressions.
client.configFile
Type: string
Default: Unset
Path to an SDK configuration file, relative to the Nuxt project root. When omitted, the module discovers mixpanel.client.config.ts in that root.
An explicit path must point to an existing file. Paths are resolved at build time and have no runtime override.
Server
server.enabled
Type: boolean
Default: true
Allow access to the Node SDK. Calling useMixpanelServer() while disabled throws.
server.token
Type: string
Default: ''
Project token passed to the Node SDK. The browser token is not used as a fallback.
server.config
Type: JSON-compatible Node SDK options
Default: {} when no configuration file is used
Options passed to server initialization. The inline type excludes credentials and logger.
Use defineMixpanelServerConfig in a configuration file for those options.
server.configFile
Type: string
Default: Unset
Path to an SDK configuration file, relative to the Nuxt project root. When omitted, the module discovers mixpanel.server.config.ts in that root.
An explicit path must point to an existing file. Paths are resolved at build time and have no runtime override.
Configuration sources
For each client, choose inline config or a configuration file. Combining both throws, including automatically discovered files and inline runtimeConfig options.
Inline configuration accepts strings, finite numbers, booleans, null, arrays and plain objects containing those values. Functions, regular expressions, undefined properties, circular references, symbols and accessor properties fail validation.
A configuration file must default-export a plain object. Factories, arrays and class instances are not accepted. Browser configuration files are loaded only when browser tracking is active.
Runtime config
Explicit runtime config values take precedence over module defaults. The module declares these runtime keys:
| Module option | Runtime config key | Environment variable |
|---|---|---|
client.enabled | public.mixpanel.client.enabled | NUXT_PUBLIC_MIXPANEL_CLIENT_ENABLED |
client.token | public.mixpanel.client.token | NUXT_PUBLIC_MIXPANEL_CLIENT_TOKEN |
client.pageviewStrategy | public.mixpanel.client.pageviewStrategy | NUXT_PUBLIC_MIXPANEL_CLIENT_PAGEVIEW_STRATEGY |
server.enabled | mixpanel.server.enabled | NUXT_MIXPANEL_SERVER_ENABLED |
server.token | mixpanel.server.token | NUXT_MIXPANEL_SERVER_TOKEN |
Inline SDK options use public.mixpanel.client.config and mixpanel.server.config. Client runtime keys are public; server keys remain private.
Type
import type { ModuleOptions, PageviewStrategy } from 'mixpanel-nuxt/config'
ModuleOptions describes the client and server sections. PageviewStrategy is 'router' | 'native'.