---
title: "Configuration"
description: "Complete configuration reference for Nuxt Skew Protection."
canonical_url: "https://nuxtseo.com/docs/skew-protection/api/config"
last_updated: "2026-09-30T20:50:13.593Z"
---

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

## Basic Configuration

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['nuxt-skew-protection'],

  skewProtection: {
    // Your configuration here
  }
})
```

## Options

### `enabled: boolean`{lang="ts"}

- Default: `true`{lang="ts"}

Enables or disables the module.

### `storage: StorageOptions`{lang="ts"}

- Default: `{ driver: 'fs', base: 'node_modules/.cache/nuxt-seo/skew-protection' }`{lang="ts"}

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

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  skewProtection: {
    storage: {
      driver: 'fs', // or 'redis', 's3', 'cloudflare-kv-binding', etc.
      // Driver-specific options
    }
  }
})
```

See [Storage Configuration](/docs/skew-protection/guides/storage-configuration) for all drivers.

### `updateStrategy: 'polling' | 'sse' | 'ws'`{lang="ts"}

- Default: Auto-detected based on platform

Strategy for checking for version updates. Pass `pusherAdapter()`{lang="ts"} or `ablyAdapter()`{lang="ts"} to use an external realtime provider.

See [Update Strategies](/docs/skew-protection/guides/update-strategies) and [External Providers](/docs/skew-protection/providers/external) for details.

### `reloadStrategy: 'prompt' | 'immediate' | 'idle' | false`{lang="ts"}

- Default: `'prompt'`{lang="ts"}

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

- `'prompt'`: show `<SkewNotification>`{lang="html"} 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 })`{lang="ts"}.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  skewProtection: {
    reloadStrategy: 'idle'
  }
})
```

### `multiTab: boolean`{lang="ts"}

- Default: `true`{lang="ts"}

Shares detected deployments between tabs of the same app through `BroadcastChannel`. One tab detects the update and the other tabs receive it. Set `false` to make each tab detect updates on its own.

### `basePath: string`{lang="ts"}

- Default: `'/__skew'`{lang="ts"}, 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`{lang="ts"}

- Default: `30`{lang="ts"}

How many days to keep old versions before cleanup.

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

### `maxNumberOfVersions: number`{lang="ts"}

- Default: `10`{lang="ts"}

Maximum number of versions to retain.

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

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

### `cookie: CookieOptions`{lang="ts"}

- Default: See below

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

If you do not set `name`, the module derives it from [`basePath`](#basepath-string): `__nkpv` at the root, `__nkpv_pro` under `/pro/__skew`.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  skewProtection: {
    cookie: {
      path: '/',
      sameSite: 'lax',
      maxAge: 60 * 60 * 24 * 7 // 7 days
    }
  }
})
```

### `bundleAssets: boolean`{lang="ts"}

- Default: `true`{lang="ts"}, or `false`{lang="ts"} 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.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  skewProtection: {
    bundleAssets: true
  }
})
```

::note
If native Vercel Skew Protection is active, the module keeps build metadata but skips persistent asset storage. Explicit configuration takes precedence.
::

### `connectionTracking: boolean`{lang="ts"}

- Default: `false`{lang="ts"}

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

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  skewProtection: {
    connectionTracking: true
  }
})
```

Use with the `useActiveConnections()`{lang="ts"} composable to display live connection stats:

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

::warning
Only works with `sse` or `ws` update strategies. Does not support polling or external adapters (Pusher/Ably).
::

::note
Stats require authorization via the `skew:authorize-stats` hook. See [Live Connection Tracking](/docs/skew-protection/guides/live-connections#authorization) for setup.
::

See [Live Connection Tracking](/docs/skew-protection/guides/live-connections) for usage examples.

### `routeTracking: boolean`{lang="ts"}

- Default: `false`{lang="ts"}

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

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  skewProtection: {
    connectionTracking: true,
    routeTracking: true
  }
})
```

When enabled, `useActiveConnections()`{lang="ts"} includes a `routes` property:

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

See [Tracking User Pages](/docs/skew-protection/guides/route-tracking) for usage examples and targeted invalidation.

### `ipTracking: boolean`{lang="ts"}

- Default: `false`{lang="ts"}

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

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  skewProtection: {
    connectionTracking: true,
    ipTracking: true
  }
})
```

When enabled, `useActiveConnections()`{lang="ts"} includes IP addresses in the `connections` array:

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

::warning
IP tracking requires explicit opt-in due to privacy considerations. The module only stores IPs in memory and exposes them via the stats API. Ensure your `skew:authorize-stats` hook properly restricts access.
::

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

### `debug: boolean`{lang="ts"}

- Default: `false`{lang="ts"}

Enables debug logging.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  skewProtection: {
    debug: true
  }
})
```

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

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.