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>
A Feathers application instance to extend with Koa functionality
A Koa application instance (defaults to new Koa())
Returns
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
REST configuration options or a custom formatter middleware
RestOptions
Custom response formatter middleware
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
Authentication parsing configuration
AuthenticationSettings
Name of the authentication service
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
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 */]
}
})
Middleware to run before the service handler
Middleware to run after the service handler
Context Extensions
The Koa context object is extended with Feathers-specific properties:
Feathers params object containing provider, headers, and other metadata
Service route lookup information
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')