Socket.io Client

API reference for @feathersjs/socketio-client providing real-time Socket.io connections for Feathers clients

Socket.io Client

The @feathersjs/socketio-client module provides real-time connectivity for Feathers client applications using Socket.io.

Installation

npm install @feathersjs/socketio-client socket.io-client

socketioClient()

Configures a Feathers client to use Socket.io for real-time communication.

Signature

function socketioClient<Services = any>(
  connection: Socket,
  options?: any
): TransportConnection<Services>

connection · Socket · required

Socket.io client connection instance from socket.io-client

options · object

Additional configuration options

Returns

TransportConnection · TransportConnection<Services>

A transport connection that can be passed to app.configure()

Example

import feathers from '@feathersjs/feathers'
import socketio from '@feathersjs/socketio-client'
import io from 'socket.io-client'

const socket = io('http://localhost:3030')
const app = feathers()

app.configure(socketio(socket))

// Use services
const messages = app.service('messages')
const message = await messages.create({ text: 'Hello!' })

Connection Options

Socket.io connection options are passed when creating the socket:

import io from 'socket.io-client'

const socket = io('http://localhost:3030', {
  transports: ['websocket'],
  reconnection: true,
  reconnectionDelay: 1000,
  reconnectionAttempts: 10,
  timeout: 20000,
  auth: {
    token: 'authentication-token'
  }
})

transports · string[] · default: "['polling', 'websocket']"

Transport methods to use (e.g., ['websocket'] for WebSocket only)

reconnection · boolean · default: "true"

Whether to automatically reconnect

reconnectionDelay · number · default: "1000"

Delay before reconnection attempt in milliseconds

reconnectionAttempts · number · default: "Infinity"

Maximum number of reconnection attempts

timeout · number · default: "20000"

Connection timeout in milliseconds

auth · object

Authentication data sent with the connection handshake

Service Methods

Socket.io client services implement all standard Feathers service methods with real-time support:

find()

const messages = app.service('messages')
const result = await messages.find({
  query: {
    $limit: 10,
    read: false
  }
})

get()

const message = await messages.get(123)

create()

const newMessage = await messages.create({
  text: 'Hello world!',
  userId: 1
})

update()

const updated = await messages.update(123, {
  text: 'Updated text',
  userId: 1
})

patch()

const patched = await messages.patch(123, {
  read: true
})

remove()

const removed = await messages.remove(123)

Real-Time Events

Socket.io clients automatically receive real-time service events:

Event Listeners

const messages = app.service('messages')

// Listen for created events
messages.on('created', (message) => {
  console.log('New message created:', message)
})

// Listen for updated events
messages.on('updated', (message) => {
  console.log('Message updated:', message)
})

// Listen for patched events
messages.on('patched', (message) => {
  console.log('Message patched:', message)
})

// Listen for removed events
messages.on('removed', (message) => {
  console.log('Message removed:', message)
})

Remove Event Listeners

const handler = (message) => {
  console.log('Message created:', message)
}

messages.on('created', handler)

// Remove specific listener
messages.removeListener('created', handler)

// Remove all listeners for an event
messages.removeAllListeners('created')

// Remove all listeners for all events
messages.removeAllListeners()

Custom Methods

Register and use custom service methods:

app.use('/messages', messageService, {
  methods: ['find', 'get', 'create', 'archive']
})

const messages = app.service('messages')

// Call custom method
await messages.archive({ messageId: 123 })

Authentication

Integrate with Feathers authentication:

import feathers from '@feathersjs/feathers'
import socketio from '@feathersjs/socketio-client'
import auth from '@feathersjs/authentication-client'
import io from 'socket.io-client'

const socket = io('http://localhost:3030')
const app = feathers()

app.configure(socketio(socket))
app.configure(auth())

// Authenticate
await app.authenticate({
  strategy: 'local',
  email: '[e-mail]',
  password: 'password'
})

// Socket connection is now authenticated
const messages = await app.service('messages').find()

Re-authentication on Reconnect

import io from 'socket.io-client'

const socket = io('http://localhost:3030')

socket.on('connect', async () => {
  console.log('Connected')
  
  // Re-authenticate after reconnection
  try {
    await app.reAuthenticate()
    console.log('Re-authenticated successfully')
  } catch (error) {
    console.error('Re-authentication failed:', error)
  }
})

socket.on('disconnect', () => {
  console.log('Disconnected')
})

Connection Events

Listen to Socket.io connection events:

import io from 'socket.io-client'

const socket = io('http://localhost:3030')

socket.on('connect', () => {
  console.log('Connected to server')
})

socket.on('disconnect', (reason) => {
  console.log('Disconnected:', reason)
})

socket.on('connect_error', (error) => {
  console.error('Connection error:', error)
})

socket.on('reconnect', (attemptNumber) => {
  console.log('Reconnected after', attemptNumber, 'attempts')
})

socket.on('reconnect_attempt', (attemptNumber) => {
  console.log('Reconnection attempt:', attemptNumber)
})

socket.on('reconnect_error', (error) => {
  console.error('Reconnection error:', error)
})

socket.on('reconnect_failed', () => {
  console.error('Reconnection failed')
})

Application Extensions

The Socket.io client extends the application with:

app.io · Socket

The Socket.io client instance for direct access

Example

const app = feathers()
app.configure(socketio(socket))

// Access socket directly
app.io.on('custom-event', (data) => {
  console.log('Custom event:', data)
})

app.io.emit('my-event', { foo: 'bar' })

Error Handling

Handle errors from service calls:

try {
  const message = await messages.get(999)
} catch (error) {
  console.log(error.name)     // 'NotFound'
  console.log(error.code)     // 404
  console.log(error.message)  // 'Not Found'
  console.log(error.data)     // Additional error data
}

Params

Socket.io client params:

query · object

Query parameters for the service method

headers · object

Custom headers (available in service hooks on server)

Example

const messages = await app.service('messages').find({
  query: {
    $limit: 10,
    userId: 123
  },
  headers: {
    'X-Custom-Header': 'value'
  }
})

Complete Example

import feathers from '@feathersjs/feathers'
import socketio from '@feathersjs/socketio-client'
import auth from '@feathersjs/authentication-client'
import io from 'socket.io-client'

// Create socket connection
const socket = io('http://localhost:3030', {
  transports: ['websocket'],
  reconnection: true
})

// Create client app
const app = feathers()

// Configure Socket.io transport
app.configure(socketio(socket))

// Configure authentication
app.configure(auth({
  storageKey: 'feathers-jwt'
}))

// Connection events
socket.on('connect', () => {
  console.log('Connected to server')
})

socket.on('disconnect', () => {
  console.log('Disconnected from server')
})

// Get service
const messages = app.service('messages')

// Listen for real-time events
messages.on('created', (message) => {
  console.log('New message:', message)
})

messages.on('removed', (message) => {
  console.log('Message removed:', message)
})

// Authenticate and use services
async function run() {
  try {
    // Authenticate
    await app.authenticate({
      strategy: 'local',
      email: '[e-mail]',
      password: 'password'
    })
    
    console.log('Authenticated successfully')
    
    // Create a message (will trigger 'created' event)
    const message = await messages.create({
      text: 'Hello from Socket.io client!'
    })
    
    console.log('Created message:', message)
    
    // Find all messages
    const result = await messages.find({
      query: { $limit: 10 }
    })
    
    console.log('Found messages:', result.data)
  } catch (error) {
    console.error('Error:', error)
  }
}

run()

Browser Usage

<!DOCTYPE html>
<html>
<head>
  <script src="https://cdn.socket.io/4.5.4/socket.io.min.js"></script>
  <script src="//unpkg.com/@feathersjs/client@^5.0.0/dist/feathers.js"></script>
</head>
<body>
  <script>
    const socket = io('http://localhost:3030')
    const app = feathers()
    
    app.configure(feathers.socketio(socket))
    app.configure(feathers.authentication())
    
    const messages = app.service('messages')
    
    messages.on('created', message => {
      console.log('New message:', message)
    })
    
    async function init() {
      await app.authenticate({
        strategy: 'local',
        email: '[e-mail]',
        password: 'password'
      })
      
      const result = await messages.find()
      console.log('Messages:', result)
    }
    
    init()
  </script>
</body>
</html>