Socket.io Transport

API reference for @feathersjs/socketio real-time transport provider

Socket.io Transport

The @feathersjs/socketio module provides real-time communication for Feathers services using Socket.io.

Installation

npm install @feathersjs/socketio socket.io

socketio()

Configures Socket.io as a real-time transport provider for Feathers services.

Signature

function socketio(
  callback?: (io: Server) => void
): (app: Application) => void

function socketio(
  options: number | Partial<ServerOptions>,
  callback?: (io: Server) => void
): (app: Application) => void

function socketio(
  port: number,
  options?: Partial<ServerOptions>,
  callback?: (io: Server) => void
): (app: Application) => void

port · number

Port number for standalone Socket.io server (when not using Express/Koa)

options · Partial<ServerOptions>

Socket.io server configuration options

callback · (io: Server) => void

Configuration callback that receives the Socket.io server instance

ServerOptions

Socket.io server options include:

cors · object

CORS configuration for Socket.io connections

path · string · default: "/socket.io"

Path where Socket.io server listens

transports · string[]

Allowed transports (e.g., ['websocket', 'polling'])

pingTimeout · number · default: "20000"

Ping timeout in milliseconds

pingInterval · number · default: "25000"

Ping interval in milliseconds

Example

import feathers from '@feathersjs/feathers'
import express from '@feathersjs/express'
import socketio from '@feathersjs/socketio'

const app = express(feathers())

// Basic setup
app.configure(socketio())

// With options
app.configure(socketio({
  cors: {
    origin: 'http://localhost:3000',
    credentials: true
  },
  transports: ['websocket']
}))

// With configuration callback
app.configure(socketio((io) => {
  io.on('connection', (socket) => {
    console.log('New socket connection:', socket.id)
  })
  
  // Custom Socket.io middleware
  io.use((socket, next) => {
    // Validate connection
    next()
  })
}))

// With port (standalone)
app.configure(socketio(3031, {
  cors: { origin: '*' }
}))

app.listen(3030)

Application Extensions

When Socket.io is configured, the application is extended with:

app.io · Server

The Socket.io server instance for direct access

Example

app.configure(socketio())

await app.listen(3030)

// Access Socket.io server
const io = app.io

// Broadcast to all clients
io.emit('news', { text: 'Important update!' })

// Access connected sockets
io.sockets.sockets.forEach((socket) => {
  console.log('Connected socket:', socket.id)
})

Connection Parameters

Socket connections automatically receive Feathers params:

socket.feathers · Params

Feathers params object with connection metadata

socket.feathers.provider · string

Set to 'socketio' for Socket.io connections

socket.feathers.headers · object

Connection handshake headers

socket.feathers.authentication · object

Parsed authentication data (when authentication is configured)

Authentication

Socket.io automatically integrates with Feathers authentication:

import socketio from '@feathersjs/socketio'
import '@feathersjs/authentication'

const app = express(feathers())

// Configure authentication first
app.configure(authentication({
  // authentication config
}))

// Socket.io will automatically parse authentication
app.configure(socketio())

Authentication is parsed from:

• Connection handshake headers
• JWT tokens in the Authorization header
• Custom authentication strategies

Events

Socket.io connections emit standard Feathers events:

Connection Events

app.on('connection', (connection) => {
  console.log('New real-time connection', connection)
})

app.on('disconnect', (connection) => {
  console.log('Connection disconnected', connection)
})

Service Events

Services automatically emit events to connected clients:

// Clients automatically receive these events:
// - created
// - updated
// - patched
// - removed

const messages = app.service('messages')

// This will emit 'created' event to all connected clients
await messages.create({ text: 'Hello!' })

Event Filtering

Control which clients receive service events:

app.service('messages').publish('created', (data, context) => {
  // Send to all authenticated users
  return app.channel('authenticated')
})

app.service('messages').publish('updated', (data, context) => {
  // Send only to the user who owns the message
  return app.channel(`user/${data.userId}`)
})

Channels

Manage Socket.io connections using channels:

app.on('connection', (connection) => {
  // Add to anonymous channel
  app.channel('anonymous').join(connection)
})

app.on('login', (authResult, { connection }) => {
  // Move authenticated users to their channel
  app.channel('anonymous').leave(connection)
  app.channel('authenticated').join(connection)
  app.channel(`user/${authResult.user.id}`).join(connection)
})

Direct Socket Access

Access the underlying Socket.io socket in service hooks:

app.service('messages').hooks({
  after: {
    create: [async (context) => {
      const { params } = context
      
      if (params.provider === 'socketio') {
        // Access socket through connection
        console.log('Socket ID:', params.connection.id)
      }
      
      return context
    }]
  }
})

Middleware

Socket.io middleware is automatically configured:

• disconnect: Handles client disconnections
• params: Sets up Feathers params on the socket
• authentication: Parses authentication credentials

Configuration with Express/Koa

import feathers from '@feathersjs/feathers'
import express from '@feathersjs/express'
import socketio from '@feathersjs/socketio'

const app = express(feathers())

// Configure transports
app.configure(express.rest())
app.configure(socketio({
  cors: {
    origin: 'http://localhost:3000',
    credentials: true
  }
}))

// Register services (available via both REST and Socket.io)
app.use('/messages', messageService)

const server = await app.listen(3030)

Complete Example

import feathers from '@feathersjs/feathers'
import express from '@feathersjs/express'
import socketio from '@feathersjs/socketio'
import { memory } from '@feathersjs/memory'

const app = express(feathers())

// Configure Socket.io
app.configure(socketio((io) => {
  io.on('connection', (socket) => {
    console.log('Client connected:', socket.id)
    
    socket.on('disconnect', () => {
      console.log('Client disconnected:', socket.id)
    })
  })
}))

// Register service
app.use('/messages', memory())

// Setup channels
app.on('connection', (connection) => {
  app.channel('everybody').join(connection)
})

// Publish events
app.publish((data, context) => {
  return app.channel('everybody')
})

// Start server
const server = await app.listen(3030)
console.log('Feathers app with Socket.io listening on port 3030')