Getting Started

Configuration

Configure storage, Redis, Socket.IO, and key cleanup for Nuxt Realtime.

All options are set under the nuxtRealtime key in nuxt.config.ts.

Storage

Nuxt Realtime uses Nitro's storage system for state persistence. Configure it with the storage option.

Memory (default)

State is stored in-process and not shared between server instances. No extra configuration needed.

nuxt.config.ts

export default defineNuxtConfig({
  nuxtRealtime: {
    storage: {
      driver: 'memory',
    },
  },
})

Redis

For persistent storage that survives server restarts. This does not sync state across multiple server instances (see Cross-Server Sync for that).

Install ioredis as a peer dependency:

pnpm add ioredis

npm install ioredis

yarn add ioredis

nuxt.config.ts

export default defineNuxtConfig({
  nuxtRealtime: {
    storage: {
      driver: 'redis',
      host: 'localhost',
      port: 6379,
    },
  },
})

See the Nitro storage documentation for all available drivers and their options.

When running multiple server instances behind a load balancer, use the redis option to broadcast state changes across instances via Redis pub/sub. Every connected client sees up-to-date values regardless of which instance they are connected to.

Install ioredis as a peer dependency:

pnpm add ioredis

npm install ioredis

yarn add ioredis

nuxt.config.ts

export default defineNuxtConfig({
  nuxtRealtime: {
    redis: {
      host: 'localhost',
      port: 6379,
    },
  },
})

Or use a connection URL:

nuxt.config.ts

export default defineNuxtConfig({
  nuxtRealtime: {
    redis: {
      url: process.env.REDIS_URL,
    },
  },
})

For Redis Cluster, use cluster instead:

nuxt.config.ts

export default defineNuxtConfig({
  nuxtRealtime: {
    redis: {
      cluster: [{ host: 'redis-1', port: 6379 }, { host: 'redis-2', port: 6379 }],
    },
  },
})

Redis options

Option	Type	Description
`host`	`string`	Redis host. Ignored when `url` is set. Defaults to `'localhost'`.
`port`	`number`	Redis port. Ignored when `url` is set. Defaults to `6379`.
`url`	`string`	Redis connection URL (e.g. `redis://localhost:6379`). Takes priority over `host`/`port`.
`cluster`	`ClusterNode[]`	Cluster nodes. Takes priority over `url`/`host`/`port`.
`clusterOptions`	`ClusterOptions`	Options passed to the ioredis cluster client (e.g. `redisOptions`, `scaleReads`).
`password`	`string`	Redis password. Ignored when `cluster` is set — use `clusterOptions.redisOptions.password` instead.
`db`	`number`	Redis database index.
`tls`	`object`	TLS options passed to ioredis.
`base`	`string`	Key prefix for all stored values.

The redis and storage options are mutually exclusive. When both are set, redis takes precedence.

Engine.IO Server Options

Pass options to the underlying Engine.IO server via socketio.serverOptions. These map to engine.io's ServerOptions (Socket.IO transport-layer options).

nuxt.config.ts

export default defineNuxtConfig({
  nuxtRealtime: {
    socketio: {
      serverUrl: 'https://realtime.example.com',
      serverOptions: {
        cors: {
          origin: ['https://myapp.com'],
          credentials: true,
        },
        maxHttpBufferSize: 1e6, // 1 MB
      },
    },
  },
})

CORS is only needed when socketio.serverUrl points at a different origin than your app. Same-origin connections work without it.

Key Cleanup

Nuxt Realtime automatically removes unused storage keys through a lease-based cleanup system. When no client has subscribed to a key for longer than the idle threshold, the key is deleted.

This is enabled by default with sensible defaults:

Option	Default	Description
`heartbeatInterval`	`30_000` ms	How often clients send a heartbeat to keep their keys alive
`cleanupInterval`	`300_000` ms	How often the server scans for and removes expired keys
`idleThreshold`	`3_600_000` ms	How long a key must be idle before it is removed

Customizing cleanup

nuxt.config.ts

export default defineNuxtConfig({
  nuxtRealtime: {
    cleanup: {
      heartbeatInterval: 30_000,   // 30s
      cleanupInterval: 300_000,    // 5 min
      idleThreshold: 3_600_000,    // 1 hour
    },
  },
})

Disabling cleanup

Set cleanup: false to opt out entirely. Useful when you manage storage lifecycle yourself or your storage driver handles expiry natively (e.g. Redis TTLs).

nuxt.config.ts

export default defineNuxtConfig({
  nuxtRealtime: {
    cleanup: false,
  },
})

Installation

Install Nuxt Realtime in your Nuxt application.

Usage

Quick overview of the Nuxt Realtime composables.