vite-plugin-socket.io

1.0.2 verified Mon Apr 27 auth: no javascript

A Vite plugin that integrates a Socket.IO server into the Vite dev server, enabling real-time WebSocket communication during development. Version 1.0.2 is the latest stable release, updated infrequently. It wraps socket.io and attaches it to the Vite HTTP server, allowing developers to define server and socket event handlers directly in the Vite config. Differentiators: minimal configuration, automatic WebSocket injection into Vite's HMR pipeline, and support for custom socket event callbacks.

Common errors

error TypeError: vitePluginSocketIO is not a function ↓

cause Using named import instead of default import.

fix

Change to: import vitePluginSocketIO from 'vite-plugin-socket.io'

error Error: Cannot find module 'socket.io' ↓

cause Socket.IO not installed as a dependency.

fix

Run: npm install socket.io

error Error: Dynamic require of "vite-plugin-socket.io" is not supported ↓

cause Using require() instead of import for an ESM-only module.

fix

Change to: import vitePluginSocketIO from 'vite-plugin-socket.io'

Warnings

gotcha The plugin only works in Vite's dev server, not during build. ↓

fix Use a separate Socket.IO server for production, or conditionally exclude the plugin.

gotcha The default export is not named; named imports will be undefined. ↓

fix Use default import syntax: import vitePluginSocketIO from 'vite-plugin-socket.io'

deprecated CJS require() is not supported; the package is ESM-only. ↓

fix Switch to ES modules or use dynamic import().

gotcha Socket.IO must be installed as a peer dependency. ↓

fix Run: npm install socket.io

Install

npm install vite-plugin-socket-io

yarn add vite-plugin-socket-io

pnpm add vite-plugin-socket-io

Imports

default

wrong

const vitePluginSocketIO = require('vite-plugin-socket.io')

correct

import vitePluginSocketIO from 'vite-plugin-socket.io'

The plugin is ESM-only; CommonJS require will fail.

vitePluginSocketIO

wrong

import { vitePluginSocketIO } from 'vite-plugin-socket.io'

correct

import { default as vitePluginSocketIO } from 'vite-plugin-socket.io'

Named import is incorrect; the module only has a default export.

type imports

wrong

import { Socket } from 'socket.io' (if value not needed)

correct

import type { Socket } from 'socket.io'

TypeScript users often incorrectly value-import when only type is needed.

Quickstart

Basic setup to add Socket.IO server to Vite dev server with no extra events.

// vite.config.js
import { defineConfig } from 'vite';
import vitePluginSocketIO from 'vite-plugin-socket.io';

export default defineConfig({
  plugins: [vitePluginSocketIO()]
});