Application API

Complete API reference for the Feathers application instance

The Feathers application is the main entry point for a Feathers server. It extends Node’s EventEmitter and provides methods for registering services, configuring the application, and managing the application lifecycle.

feathers()

Creates a new Feathers application instance.

import { feathers } from '@feathersjs/feathers'

const app = feathers<Services, Settings>()

Services · object

Type definition for all services registered on the application

Settings · object

Type definition for application settings

app · Application<Services, Settings>

A new Feathers application instance

Properties

version

app.version: string

The Feathers version number.

import { feathers } from '@feathersjs/feathers'

const app = feathers()
console.log(app.version) // e.g., "5.0.0"

services

app.services: Services

An object containing all registered services keyed by their path.

Services should always be retrieved via app.service('name') not via app.services. Direct access to app.services is not recommended.

settings

app.settings: Settings

An object containing all application settings that can be accessed via app.get() and app.set().

mixins

app.mixins: ServiceMixin<Application<Services, Settings>>[]

A list of callbacks that run when a new service is registered. Used internally for adding hooks and events functionality.

app.mixins.push((service, path, options) => {
  console.log(`Registered service at ${path}`)
})

Methods

get()

Retrieve an application setting by name.

get<L extends keyof Settings & string>(name: L): Settings[L]

name · string · required

The setting name

value · any

The setting value, or undefined if not set

app.set('port', 3030)
const port = app.get('port') // 3030

set()

Set an application setting.

set<L extends keyof Settings & string>(name: L, value: Settings[L]): this

name · string · required

The setting name

value · any · required

The setting value

app · Application

The application instance for chaining

app.set('port', 3030)
  .set('host', 'localhost')
  .set('env', 'development')

configure()

Runs a callback configure function with the current application instance.

configure(callback: (this: this, app: this) => void): this

callback · function · required

The callback (app: Application) => void to run. The callback is called with this bound to the app instance.

app · Application

The application instance for chaining

import { feathers } from '@feathersjs/feathers'

const configureApp = (app) => {
  app.set('port', 3030)
  app.set('host', 'localhost')
}

const app = feathers()
  .configure(configureApp)

use()

Register a new service or a sub-app. When passed another Feathers application, all its services will be re-registered with the path prefix.

use<L extends keyof Services & string>(
  path: L,
  service: ServiceInterface | Application,
  options?: ServiceOptions
): this

path · string · required

The path for the service to register (e.g., '/users', '/api')

service · ServiceInterface | Application · required

The service object to register or another Feathers application to use as a sub-app

options · ServiceOptions

Configuration options for this service

options.methods · string[]

A list of service methods that should be available externally to clients

options.events · string[]

A list of custom events that this service emits to clients

options.serviceEvents · string[]

Provide a full list of events that this service should emit. Unlike events, this will not be merged with the default events.

app · Application

The application instance for chaining

// Register a service
app.use('/users', {
  async find(params) {
    return []
  },
  async get(id, params) {
    return { id }
  }
})

// Register with options
app.use('/messages', messageService, {
  methods: ['find', 'get', 'create'],
  events: ['typing']
})

// Register a sub-app
const subApp = feathers()
subApp.use('/service1', service1)
app.use('/api', subApp) // Mounts at /api/service1

service()

Get the Feathers service instance for a path. This will be the service originally registered with Feathers functionality like hooks and events added.

service<L extends keyof Services & string>(
  path: L
): FeathersService<this, Services[L]>

path · string · required

The name of the service (e.g., 'users', '/api/messages')

service · FeathersService

The service instance with hooks and events

const userService = app.service('users')
const user = await userService.get(1)

unuse()

Unregister an existing service. Calls teardown on the service if it exists.

unuse<L extends keyof Services & string>(
  path: L
): Promise<FeathersService<this, Services[L]>>

path · string · required

The name of the service to unregister

service · Promise<FeathersService>

The unregistered service instance

const removedService = await app.unuse('users')

setup()

Set up the application and call all services’ .setup() method if available.

setup(server?: any): Promise<this>

server · any

A server instance (e.g., HTTP server)

app · Promise<Application>

The application instance

import { feathers } from '@feathersjs/feathers'
import { createServer } from 'http'

const app = feathers()

app.use('/users', userService)

const server = createServer(app)
await app.setup(server)

server.listen(3030)

teardown()

Tear down the application and call all services’ .teardown() method if available.

teardown(server?: any): Promise<this>

server · any

A server instance (e.g., HTTP server)

app · Promise<Application>

The application instance

// Graceful shutdown
process.on('SIGTERM', async () => {
  await app.teardown()
  process.exit(0)
})

hooks()

Register application-level hooks that run for all services.

hooks(map: ApplicationHookOptions<this>): this

map · ApplicationHookOptions · required

The application hook settings

app · Application

The application instance for chaining

See the Hooks API for details on hook types and usage.

// Register hooks for all services
app.hooks({
  before: {
    all: [authenticate('jwt')]
  },
  error: {
    all: [logError]
  }
})

// Register setup/teardown hooks
app.hooks({
  setup: [initializeDatabase],
  teardown: [closeConnections]
})

defaultService()

Returns a fallback service instance that will be registered when no service was found. Usually throws a NotFound error but also used to instantiate client-side services.

defaultService(location: string): ServiceInterface

location · string · required

The path of the service

service · ServiceInterface

A fallback service instance

// Override default behavior
app.defaultService = (location) => {
  return {
    async get(id) {
      return { id, location }
    }
  }
}

Events

The Feathers application extends Node’s EventEmitter, so you can use all EventEmitter methods:

// Listen for events
app.on('event-name', (data) => {
  console.log('Event received:', data)
})

// Emit events
app.emit('event-name', { some: 'data' })

// Remove listener
app.removeListener('event-name', listener)

Type Definitions

interface Application<Services = any, Settings = any>
  extends FeathersApplication<Services, Settings>, EventEmitter {
  version: string
  services: Services
  settings: Settings
  mixins: ServiceMixin<Application<Services, Settings>>[]
  _isSetup: boolean
  
  get<L extends keyof Settings & string>(name: L): Settings[L]
  set<L extends keyof Settings & string>(name: L, value: Settings[L]): this
  configure(callback: (this: this, app: this) => void): this
  use<L extends keyof Services & string>(
    path: L,
    service: ServiceInterface | Application,
    options?: ServiceOptions
  ): this
  service<L extends keyof Services & string>(path: L): FeathersService<this, Services[L]>
  unuse<L extends keyof Services & string>(path: L): Promise<FeathersService<this, Services[L]>>
  setup(server?: any): Promise<this>
  teardown(server?: any): Promise<this>
  hooks(map: ApplicationHookOptions<this>): this
  defaultService(location: string): ServiceInterface
}