Getting Started

Installation

Install and configure Nuxt Realtime in your Nuxt application.

Quick Start

Install the module with one command:

pnpm add nuxt-realtime

npm install nuxt-realtime

yarn add nuxt-realtime

npx nuxi module add nuxt-realtime

Configuration

Add nuxt-realtime to your nuxt.config.ts:

nuxt.config.ts

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

  // Enable WebSocket support in Nitro
  nitro: {
    experimental: {
      websocket: true,
    },
  },

  // Optional: Configure the module
  nuxtRealtime: {
    storage: {
      driver: 'memory', // Default storage driver
    },
  },
})

Storage Configuration

Nuxt Realtime uses Nitro's storage system for state persistence. You can configure different storage drivers:

Memory (Default)

State is stored in-process and is not shared between server instances.

nuxt.config.ts

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

Redis (single server)

For persistent storage that survives server restarts, configure Nitro's built-in Redis driver via the storage option. Note that this does not sync state across multiple server instances.

nuxt.config.ts

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

See the Nitro storage documentation for all available drivers.

Cross-Server Sync

When running multiple server instances (e.g. behind a load balancer), state changes need to be broadcast across all instances so every connected client sees up-to-date values.

Use the redis option to enable cross-server sync via Redis pub/sub. The module will automatically use the built-in reactiveRedisDriver which layers pub/sub change notifications on top of standard Redis storage.

Install peer dependency

npm install ioredis

nuxt.config.ts

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

You can also use a connection URL:

nuxt.config.ts

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

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`.
`password`	`string`	Redis password.
`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.

Key Cleanup

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

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. Use this if you manage storage lifecycle yourself or if your storage driver handles expiry natively (e.g. Redis TTLs).

nuxt.config.ts

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

Requirements

Nuxt 3.x or Nuxt 4.x
Node.js 18+
WebSocket support enabled in Nitro

That's it! You can now use the realtime composables in your components.

Introduction

Real-time state synchronization for Nuxt applications.

Usage

Quick overview of the Nuxt Realtime composables.