Koa Transport

API reference for @feathersjs/koa transport including REST provider and Koa framework bindings

Koa Transport

The @feathersjs/koa module provides Koa framework bindings and a REST API provider for Feathers applications.

Installation

npm install @feathersjs/koa koa

koa()

Creates a Feathers application that extends a Koa app with Feathers functionality.

Signature

function koa<S = any, C = any>(
  feathersApp?: FeathersApplication<S, C>,
  koaApp?: Koa
): Application<S, C>

feathersApp · FeathersApplication

A Feathers application instance to extend with Koa functionality

koaApp · Koa

A Koa application instance (defaults to new Koa())

Returns

Application · Application<S, C>

Combined Koa and Feathers application with extended functionality including:

• All Koa app methods and middleware
• All Feathers service and hook capabilities
• Enhanced listen() method that calls Feathers setup()
• Enhanced use() method that handles both Koa middleware and Feathers services

Example

import feathers from '@feathersjs/feathers'
import { koa, rest, bodyParser } from '@feathersjs/koa'

const app = koa(feathers())

// Koa middleware
app.use(bodyParser())

// Feathers REST transport
app.configure(rest())

// Register services
app.use('/messages', messageService)

// Start server
app.listen(3030)

rest()

Configures the REST transport provider for Feathers services.

Signature

function rest(options?: RestOptions | Middleware): (app: Application) => void

options · RestOptions | Middleware

REST configuration options or a custom formatter middleware

RestOptions

formatter · Middleware

Custom response formatter middleware

authentication · AuthenticationSettings

Authentication configuration for parsing credentials from HTTP requests

Example

import { koa, rest } from '@feathersjs/koa'

const app = koa(feathers())

// Use default REST provider
app.configure(rest())

// With custom formatter
app.configure(rest(async (ctx, next) => {
  await next()
  // Custom formatting logic
}))

// With authentication options
app.configure(rest({
  authentication: {
    service: 'authentication',
    strategies: ['jwt', 'local']
  }
}))

parseAuthentication()

Middleware that parses authentication credentials from HTTP headers.

Signature

function parseAuthentication(settings?: AuthenticationSettings): Middleware

settings · AuthenticationSettings

Authentication parsing configuration

AuthenticationSettings

service · string

Name of the authentication service

strategies · string[]

Array of authentication strategy names to parse

Example

import { koa, parseAuthentication } from '@feathersjs/koa'

const app = koa(feathers())

// Automatically parse authentication from headers
app.use(parseAuthentication({
  strategies: ['jwt', 'api-key']
}))

authenticate()

Koa middleware for authenticating requests.

Signature

function authenticate(
  settings: string | AuthenticationSettings,
  ...strategies: string[]
): Middleware

settings · string | AuthenticationSettings

Authentication service name or settings object

strategies · string[]

Authentication strategies to use

Example

import { koa, authenticate } from '@feathersjs/koa'

const app = koa(feathers())

// Protect specific routes
app.use(authenticate('jwt'))

// Protect a service with specific strategies
app.use('/messages', authenticate('jwt'), messageService)

Exported Koa Utilities

The module exports commonly used Koa utilities:

import {
  Koa,            // Koa class
  bodyParser,     // koa-body parser (koaBody)
  cors,           // @koa/cors middleware
  serveStatic     // koa-static for serving files
} from '@feathersjs/koa'

bodyParser Options

app.use(bodyParser({
  multipart: true,
  urlencoded: true,
  json: true
}))

CORS Configuration

import { cors } from '@feathersjs/koa'

app.use(cors({
  origin: '*',
  credentials: true
}))

Static File Serving

import { serveStatic } from '@feathersjs/koa'

app.use(serveStatic('public'))

Service Options

Koa-specific service options can be configured when registering services:

app.use('/messages', messageService, {
  koa: {
    before: [/* middleware before service */],
    after: [/* middleware after service */]
  }
})

koa.before · Middleware[]

Middleware to run before the service handler

koa.after · Middleware[]

Middleware to run after the service handler

Context Extensions

The Koa context object is extended with Feathers-specific properties:

ctx.feathers · Params

Feathers params object containing provider, headers, and other metadata

ctx.lookup · RouteLookup

Service route lookup information

ctx.hook · HookContext

The hook context from the service call

Middleware Type

Koa middleware in Feathers uses the following type signature:

type Middleware<A = Application> = (
  context: FeathersKoaContext<A>,
  next: Next
) => any

type FeathersKoaContext<A = Application> = Koa.Context & {
  app: A
}

Complete Example

import feathers from '@feathersjs/feathers'
import { koa, rest, bodyParser, cors, serveStatic } from '@feathersjs/koa'

const app = koa(feathers())

// Middleware
app.use(cors())
app.use(serveStatic('public'))
app.use(bodyParser({
  multipart: true
}))

// Configure REST transport
app.configure(rest())

// Register services
app.use('/messages', messageService, {
  koa: {
    before: [
      async (ctx, next) => {
        console.log('Before service call')
        await next()
      }
    ]
  }
})

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