Skip to main content
The @feathersjs/client package provides a complete Feathers client build that consolidates all client-side modules into a single package. It includes support for REST and WebSocket connections, authentication, and error handling.

​
Installation

npm install @feathersjs/client

​
Browser Usage

You can also use the pre-built browser bundle: 
<script src="//unpkg.com/@feathersjs/client@^5.0.0/dist/feathers.js"></script>
<script>
  const client = feathers()
</script>

​
Basic Usage

​
REST Client with Fetch

import feathers from '@feathersjs/client'

const client = feathers()

// Configure REST client
const restClient = feathers.rest('http://localhost:3030')
client.configure(restClient.fetch(window.fetch.bind(window)))

// Configure authentication
client.configure(feathers.authentication())

// Use services
const messages = client.service('messages')
const result = await messages.find()

​
Socket.io Client

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

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

// Configure Socket.io client
client.configure(feathers.socketio(socket))

// Configure authentication
client.configure(feathers.authentication())

// Real-time events
const messages = client.service('messages')
messages.on('created', (message) => {
  console.log('New message:', message)
})

​
Exported Modules

The client package re-exports all necessary modules:

​
Core

import feathers from '@feathersjs/client'
// Default export is the feathers() function

// Also exports everything from @feathersjs/feathers
import { 
  Application,
  Service,
  HookContext,
  // ... all feathers types and utilities
} from '@feathersjs/client'

​
Authentication

import { authentication } from '@feathersjs/client'

const client = feathers()
client.configure(authentication({
  storage: window.localStorage
}))
​
options
object
Authentication configuration options
​
storage
Storage
Storage instance for JWT token (defaults to localStorage in browser)
​
storageKey
string
Key name for storing the JWT (defaults to ‘feathers-jwt’)
​
jwtStrategy
string
Name of the JWT authentication strategy (defaults to ‘jwt’)

​
REST Client

import { rest } from '@feathersjs/client'

const restClient = rest('http://api.example.com')

// With fetch
client.configure(restClient.fetch(window.fetch.bind(window)))

// With custom headers
client.configure(restClient.fetch(window.fetch.bind(window), {
  headers: {
    'X-Custom-Header': 'value'
  }
}))
​
baseUrl
string
The base URL of the Feathers API server
​
return
RestClient
REST client instance with transport methods (fetch, axios, etc.)

​
Socket.io Client

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

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

client.configure(socketio(socket))
​
socket
Socket
Socket.io client instance
​
options
object
Socket.io client configuration
​
timeout
number
Request timeout in milliseconds

​
Error Handling

import { errors } from '@feathersjs/client'

try {
  await messages.create({ text: '' })
} catch (error) {
  if (error instanceof errors.BadRequest) {
    console.error('Invalid request:', error.message)
  } else if (error instanceof errors.NotAuthenticated) {
    console.error('Please log in')
  }
}
Available error classes:
  • BadRequest (400)
  • NotAuthenticated (401)
  • PaymentError (402)
  • Forbidden (403)
  • NotFound (404)
  • MethodNotAllowed (405)
  • NotAcceptable (406)
  • Timeout (408)
  • Conflict (409)
  • Unprocessable (422)
  • TooManyRequests (429)
  • GeneralError (500)
  • NotImplemented (501)
  • Unavailable (503)

​
Complete Examples

​
Browser Client with Authentication

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

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

// Configure transport
client.configure(feathers.socketio(socket))

// Configure authentication
client.configure(feathers.authentication({
  storage: window.localStorage
}))

// Login
async function login(email: string, password: string) {
  try {
    const { accessToken } = await client.authenticate({
      strategy: 'local',
      email,
      password
    })
    console.log('Logged in successfully')
    return accessToken
  } catch (error) {
    console.error('Login failed:', error.message)
  }
}

// Use authenticated service
async function createMessage(text: string) {
  const messages = client.service('messages')
  try {
    const message = await messages.create({ text })
    return message
  } catch (error) {
    if (error instanceof feathers.errors.NotAuthenticated) {
      await login('[email protected]', 'password')
      return createMessage(text)
    }
    throw error
  }
}

​
Node.js Client

import feathers from '@feathersjs/client'
import fetch from 'node-fetch'

const client = feathers()

// Configure REST client with node-fetch
const restClient = feathers.rest('http://localhost:3030')
client.configure(restClient.fetch(fetch))

// Configure authentication
client.configure(feathers.authentication({
  storage: {
    getItem: (key: string) => Promise.resolve(null),
    setItem: (key: string, value: string) => Promise.resolve(),
    removeItem: (key: string) => Promise.resolve()
  }
}))

// Use services
const users = client.service('users')
const userList = await users.find({
  query: { $limit: 10 }
})

​
Real-time Events

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

const socket = io('http://localhost:3030')
const client = feathers()
client.configure(feathers.socketio(socket))

const messages = client.service('messages')

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

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

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

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

// Remove event listener
const handler = (message) => console.log(message)
messages.on('created', handler)
messages.off('created', handler)

​
TypeScript Support

The client package includes full TypeScript support: 
import feathers, { Application } from '@feathersjs/client'
import { User, Message } from './types'

interface ServiceTypes {
  users: User
  messages: Message
}

const client: Application<ServiceTypes> = feathers()

// Type-safe service access
const users = client.service('users')
const user: User = await users.get(1)

const messages = client.service('messages')
const messageList = await messages.find({
  query: { userId: user.id }
})

​
Browser Bundles

The package provides several pre-built browser bundles:
  • dist/feathers.js - Full client with all features
  • dist/feathers.min.js - Minified full client
  • dist/core.js - Core only (no transport or auth)
  • dist/core.min.js - Minified core
Use in HTML: 
<!-- Full client -->
<script src="//unpkg.com/@feathersjs/client@^5.0.0/dist/feathers.min.js"></script>

<!-- Core only -->
<script src="//unpkg.com/@feathersjs/client@^5.0.0/dist/core.min.js"></script>

​
Module Export Pattern

The package uses a special export pattern for CommonJS compatibility: 
import feathers from '@feathersjs/client'

// Default export is the feathers function
const app = feathers()

// Also available as named exports
import { authentication, rest, socketio, errors } from '@feathersjs/client'
In CommonJS: 
const feathers = require('@feathersjs/client')
const { authentication, rest, socketio } = require('@feathersjs/client')

// Both work
const app1 = feathers()
const app2 = feathers.default()

Build docs developers (and LLMs) love

Get started for freeTalk to us