Configuration

Set these options under skewProtection in nuxt.config.ts.

Basic Configuration

export default defineNuxtConfig({
  modules: ['nuxt-skew-protection'],

  skewProtection: {
    // Your configuration here
  }
})

Options

enabled: boolean

• Default: true

Enables or disables the module.

storage: StorageOptions

• Default: { driver: 'fs-lite', base: 'node_modules/.cache/nuxt-seo/skew-protection' }

Storage configuration for version assets and metadata. Required for production.

This default comes from the module. @nuxtjs/seo does not change it. If CI starts from a clean checkout, cache node_modules/.cache/nuxt-seo/skew-protection between builds.

export default defineNuxtConfig({
  skewProtection: {
    storage: {
      driver: 'fs-lite', // or 'redis', 's3', 'cloudflare-kv-binding', etc.
      // Driver-specific options
    }
  }
})

See Storage Configuration for all drivers.

updateStrategy: 'polling' | 'sse' | 'ws'

• Default: 'polling', using Nuxt's native manifest check once per hour.

Strategy for checking for version updates. Pass pusherAdapter() or ablyAdapter() to use an external realtime provider.

@nuxtjs/seo sets 'polling', the same value as the module default.

See Update Strategies and External Providers for details.

reloadStrategy: 'prompt' | 'immediate' | 'idle' | false

• Default: 'prompt'

What happens when a new deployment invalidates the chunks this tab loaded.

• 'prompt': show <SkewNotification> and let the user decide.
• 'immediate': reload at once.
• 'idle': reload once the user has not interacted with the page for 60 seconds, or as soon as the tab is hidden.
• false: do nothing. Use the skew:chunks-outdated hook for custom logic.

Every automatic reload calls reloadNuxtApp({ force: true, persistState: true }).

export default defineNuxtConfig({
  skewProtection: {
    reloadStrategy: 'idle'
  }
})

multiTab: boolean

• Default: true

Shares complete deployment manifests between tabs of the same app through BroadcastChannel. When you disable connectionTracking, push strategies share one connection through Web Locks. Without either browser API, each tab opens its own connection. Set false to keep detection and connections independent. Native Nuxt polling remains per tab; the module adds no polling timers.

basePath: string

• Default: '/__skew', auto-detected from the app mount point

Path prefix for the module endpoints (/sse, /ws, /health, /route, /subscribe-stats, /admin/stats, /asset). It is the full public path, including app.baseURL: app.baseURL: '/app/' gives /app/__skew. If app.buildAssetsDir is absolute, such as /pro/_nuxt/, the prefix becomes /pro/__skew. Set it only if the auto-detected path is wrong for your routing. A value outside app.baseURL moves under it, because Nitro serves nothing outside app.baseURL.

The default cookie name follows the same prefix: /pro/__skew uses the cookie __nkpv_pro.

retentionDays: number

• Default: 30

How many days to keep old versions before cleanup.

skewProtection: {
  retentionDays: 7 // Keep versions for 7 days
}

maxNumberOfVersions: number

• Default: 10

Maximum number of versions to retain.

skewProtection: {
  maxNumberOfVersions: 5 // Keep max 5 versions
}

Cleanup happens during build. The module removes the oldest versions first.

cookie: CookieOptions

• Default: See below

Cookie configuration for storing deployment version. Set false to disable the cookie.

@nuxtjs/seo sets cookie: false. Without the cookie, isClientOutdated(event) always returns false. To use server version checks, set a cookie object.

If you do not set name, the module derives it from basePath: __nkpv at the root, __nkpv_pro under /pro/__skew.

export default defineNuxtConfig({
  skewProtection: {
    cookie: {
      path: '/',
      sameSite: 'lax',
      maxAge: 60 * 60 * 24 * 7 // 7 days
    }
  }
})

bundleAssets: boolean

• Default: true, or false when native Vercel Skew Protection is active

Bundles previous build assets so users can load them before refreshing to the new version.

If false, the module still records deleted chunk metadata for service worker invalidation.

export default defineNuxtConfig({
  skewProtection: {
    bundleAssets: true
  }
})

connectionTracking: boolean

• Default: false

Enables real-time connection tracking. When enabled, the server tracks active SSE/WebSocket connections and only sends stats to authorized connections.

export default defineNuxtConfig({
  skewProtection: {
    connectionTracking: true
  }
})

Use with the useActiveConnections() composable to display live connection stats:

const { total, versions, authorized } = useActiveConnections()

See Live Connection Tracking for usage examples.

routeTracking: boolean

• Default: false

Tracks which routes users are currently viewing. Requires connectionTracking: true.

export default defineNuxtConfig({
  skewProtection: {
    connectionTracking: true,
    routeTracking: true
  }
})

When enabled, useActiveConnections() includes a routes property:

const { total, versions, routes } = useActiveConnections()
// routes.value = { "/": 10, "/about": 3, "/blog/post-1": 2 }

See Tracking User Pages for usage examples and targeted invalidation.

ipTracking: boolean

• Default: false

Tracks IP addresses of connected users. Requires connectionTracking: true.

export default defineNuxtConfig({
  skewProtection: {
    connectionTracking: true,
    ipTracking: true
  }
})

When enabled, useActiveConnections() includes IP addresses in the connections array:

const { connections } = useActiveConnections()
// connections.value = [{ id: 'abc', version: '...', route: '/', ip: '192.168.1.1' }]

The module extracts IP addresses from headers in this order: cf-connecting-ip (Cloudflare), x-forwarded-for (proxies), x-real-ip (nginx).

debug: boolean

• Default: false

Enables debug logging.

export default defineNuxtConfig({
  skewProtection: {
    debug: true
  }
})

Logs version changes, asset operations, module invalidations, and storage operations.