feathersKoa
npm install @feathersjs/koa --save
npm install @feathersjs/koa --save
The @feathersjs/koa module contains the KoaJS framework integrations for Feathers. It will turn the Feathers app into a fully compatible KoaJS application.
koa(app)
koa(app) -> app is a function that turns a Feathers application into a fully KoaJS compatible application that additionally to Feathers functionality also lets you use the KoaJS API.
import { feathers } from '@feathersjs/feathers'
import { koa, errorHandler, bodyParser, rest } from '@feathersjs/koa'
// Create an app that is a Feathers AND Express application
const app = koa(feathers())
app.use(errorHandler())
app.use(authentication())
app.use(bodyParser())
app.configure(rest())
import { feathers } from '@feathersjs/feathers'
import { koa, errorHandler, bodyParser, rest } from '@feathersjs/koa'
// Create an app that is a Feathers AND Express application
const app = koa(feathers())
app.use(errorHandler())
app.use(authentication())
app.use(bodyParser())
app.configure(rest())
import { feathers } from '@feathersjs/feathers'
import { koa, errorHandler, bodyParser, rest } from '@feathersjs/koa'
// Create an app that is a Feathers AND Express application
const app = koa(feathers())
app.use(errorHandler())
app.use(authentication())
app.use(bodyParser())
app.configure(rest())
import { feathers } from '@feathersjs/feathers'
import { koa, errorHandler, bodyParser, rest } from '@feathersjs/koa'
// Create an app that is a Feathers AND Express application
const app = koa(feathers())
app.use(errorHandler())
app.use(authentication())
app.use(bodyParser())
app.configure(rest())
@feathersjs/koa also exposes the following middleware:
rest- A middleware to expose services as REST APIsauthentication- A middleware for parsing HTTP headers for Feathers authentication informationbodyParser- The koa-bodyparser middleware for parsing request bodieserrorHandler- A JSON error handler middleware. Should always be registered as the very first middleware.
koa(app, koaApp)
koa(app, koaApp) -> app allows to extend an existing Koa application with the Feathers application app.
koa()
If no Feathers application is passed, koa() -> app returns a plain Koa application (new Koa()).
app.use(location|mw[, service])
app.use(location|mw[, service]) -> app registers either a service object, or a Koa middleware. If a path and service object is passed it will use Feathers registration mechanism, for a middleware function Koa.
Koa middleware
In a Koa middleware, ctx.feathers is an object which will be extended as params in a service method call.
import type { NextFunction } from '@feathersjs/koa'
import type { Id, Params } from '@feathersjs/feathers'
class TodoService {
async get(id: Id, params: Params & { fromMiddleware: string }) {
const { fromMiddleware } = params
return { id, fromMiddleware }
}
}
// Register Koa middleware
app.use(async (ctx: any, next: NextFunction) => {
ctx.feathers.fromMiddleware = 'Hello from Koa middleware'
await next()
})
// Register a service
app.use('todos', new TodoService())
import type { NextFunction } from '@feathersjs/koa'
import type { Id, Params } from '@feathersjs/feathers'
class TodoService {
async get(id: Id, params: Params & { fromMiddleware: string }) {
const { fromMiddleware } = params
return { id, fromMiddleware }
}
}
// Register Koa middleware
app.use(async (ctx: any, next: NextFunction) => {
ctx.feathers.fromMiddleware = 'Hello from Koa middleware'
await next()
})
// Register a service
app.use('todos', new TodoService())
class TodoService {
async get(id, params) {
const { fromMiddleware } = params
return { id, fromMiddleware }
}
}
// Register Koa middleware
app.use(async (ctx, next) => {
ctx.feathers.fromMiddleware = 'Hello from Koa middleware'
await next()
})
// Register a service
app.use('todos', new TodoService())
export {}
class TodoService {
async get(id, params) {
const { fromMiddleware } = params
return { id, fromMiddleware }
}
}
// Register Koa middleware
app.use(async (ctx, next) => {
ctx.feathers.fromMiddleware = 'Hello from Koa middleware'
await next()
})
// Register a service
app.use('todos', new TodoService())
export {}
Service middleware
When registering a service, it is also possible to pass custom Koa middleware that should run before the specific service method in the koa service option:
app.use('/todos', new TodoService(), {
koa: {
before: [
async (ctx, next) => {
ctx.feathers // data that will be merged into sevice `params`
// This will run all subsequent middleware and the service call
await next()
// Then we have additional properties available on the context
ctx.hook // the hook context from the method call
ctx.body // the return value
}
]
}
})
app.use('/todos', new TodoService(), {
koa: {
before: [
async (ctx, next) => {
ctx.feathers // data that will be merged into sevice `params`
// This will run all subsequent middleware and the service call
await next()
// Then we have additional properties available on the context
ctx.hook // the hook context from the method call
ctx.body // the return value
}
]
}
})
app.use('/todos', new TodoService(), {
koa: {
before: [
async (ctx, next) => {
ctx.feathers // data that will be merged into sevice `params`
// This will run all subsequent middleware and the service call
await next()
// Then we have additional properties available on the context
ctx.hook // the hook context from the method call
ctx.body // the return value
}
]
}
})
app.use('/todos', new TodoService(), {
koa: {
before: [
async (ctx, next) => {
ctx.feathers // data that will be merged into sevice `params`
// This will run all subsequent middleware and the service call
await next()
// Then we have additional properties available on the context
ctx.hook // the hook context from the method call
ctx.body // the return value
}
]
}
})
Note that the order of middleware will be [...before, serviceMethod].
app.listen(port)
app.listen(port) -> HttpServer will first call Koa app.listen and then internally also call the Feathers app.setup(server).
// Listen on port 3030
const server = await app.listen(3030)
// Listen on port 3030
const server = await app.listen(3030)
app.setup(server)
app.setup(server) -> app is usually called internally by app.listen but in the cases described below needs to be called explicitly.
Middleware
rest
import { rest } from '@feathersjs/koa'
app.configure(rest())
import { rest } from '@feathersjs/koa'
app.configure(rest())
import { rest } from '@feathersjs/koa'
app.configure(rest())
import { rest } from '@feathersjs/koa'
app.configure(rest())
Configures the middleware for handling service calls via HTTP. It will also register authentication header parsing. The following (optional) options are available:
formatter- A middleware that formats the response bodyauthentication- The authenticationserviceandstrategiesto use for parsing authentication information
errorHandler
import { errorHandler } from '@feathersjs/koa'
app.configure(errorHandler())
import { errorHandler } from '@feathersjs/koa'
app.configure(errorHandler())
import { errorHandler } from '@feathersjs/koa'
app.configure(errorHandler())
import { errorHandler } from '@feathersjs/koa'
app.configure(errorHandler())
A middleware that formats errors as a Feathers error and sets the proper status code. Needs to be the first middleware registered in order to catch all other errors.
authenticate
A middleware that allows to authenticate a user (or other authentication entity) setting ctx.feathers.user. Not necessary for use with services but can be used in custom middleware.
bodyParser
A reference to the koa-bodyparser module.