Required dependencies

npm install @feathersjs/feathers @feathersjs/errors @feathersjs/commons
npm install @feathersjs/express @feathersjs/socketio          # transports
npm install @feathersjs/authentication @feathersjs/authentication-local
npm install @feathersjs/authentication-client
npm install @feathersjs/adapter-commons
npm install @feathersjs/schema @feathersjs/typebox             # validation
npm install @feathersjs/configuration                          # config loader
npm install jsonwebtoken                                       # JWT peer dep
npm install typescript ts-node --save-dev

No native build steps, pod installs, or binary compilation are required for the pure Node.js usage path.

Project setup

1. Copy the source/ directory into your project root (e.g. ./source/).
2. In tsconfig.json add path aliases so local builds resolve against the source packages instead of published npm versions:

   {
     "compilerOptions": {
       "baseUrl": ".",
       "paths": {
         "@feathersjs/feathers": ["source/feathers/src"],
         "@feathersjs/errors": ["source/errors/src"],
         "@feathersjs/commons": ["source/commons/src"],
         "@feathersjs/authentication": ["source/authentication/src"],
         "@feathersjs/authentication-client": ["source/authentication-client/src"],
         "@feathersjs/adapter-commons": ["source/adapter-commons/src"]
       }
     }
   }
   

3. Reference each sub-package's tsconfig.json in a references array if you need project-reference builds.
4. Set environment variables:

   NODE_CONFIG_DIR=./config   # for @feathersjs/configuration
   

5. Run npm install in the monorepo root to hoist shared devDependencies, or install individually in each source/<package>/ directory.

Public API

select

import { select } from './source/adapter-commons/src'

function select(params: Params, ...otherFields: string[]): (result: any) => any

Returns a function that filters a result object or array to only the fields listed in params.query.$select plus any extra otherFields you name. Use it at the end of custom find/get implementations to honour client field projection without extra boilerplate.

adapterTests

import adapterTests, { AdapterTestName } from './source/adapter-tests/src'

const adapterTests: (testNames: AdapterTestName[]) => (
  app: any,
  errors: any,
  serviceName: any,
  idProp?: string
) => void

Registers the standard Feathers adapter test suite inside an existing Mocha describe block. Pass the list of test names you want to run; the function warns if a requested name is not found in the suite. Use this to validate any new database adapter against the canonical Feathers contract.

AuthenticationService

import { AuthenticationService } from './source/authentication/src'

class AuthenticationService extends AuthenticationBase {
  // registers strategies, issues/verifies JWTs, exposes /authentication endpoint
}

The central server-side authentication class. Register it on your Feathers app at the /authentication path, attach one or more strategies (e.g. JWTStrategy, LocalStrategy), and it handles token creation, verification, and revocation automatically via the standard Feathers service interface.

authenticate (hook)

import { authenticate } from './source/authentication/src'
// or
import { hooks } from './source/authentication/src'
// hooks.authenticate, hooks.connection, hooks.event

A Feathers hook that protects service methods. Accepts one or more strategy names; throws NotAuthenticated if no valid token/session matches. Use it in app.service('messages').hooks({ before: { all: [authenticate('jwt')] } }).

Working examples

Scenario - Bootstrapping a minimal Feathers app with authentication

Creates a Feathers application, registers the authentication service with a JWT strategy, and protects a messages service.

import { feathers } from '@feathersjs/feathers'
import { AuthenticationService, JWTStrategy, authenticate } from '@feathersjs/authentication'
import { MemoryService } from '@feathersjs/memory'

const app = feathers()

const authService = new AuthenticationService(app)
authService.register('jwt', new JWTStrategy())

app.use('/authentication', authService)
app.use('/messages', new MemoryService())

app.service('messages').hooks({
  before: {
    all: [authenticate('jwt')]
  }
})

app.listen(3030).then(() => console.log('Feathers running on port 3030'))

Scenario - Running the standard adapter test suite against a custom adapter

Validates a custom adapter implementation against all standard Feathers CRUD + query contracts.

import { adapterTests } from './source/adapter-tests/src'
import { feathers } from '@feathersjs/feathers'
import errors from '@feathersjs/errors'
import MyCustomAdapter from './my-adapter'

const testNames = [
  '.get', '.find', '.create', '.update', '.patch', '.remove',
  '.find + equal', '.find + $limit', '.find + $skip'
]

const app = feathers()
app.use('/test', new MyCustomAdapter({ paginate: { default: 10, max: 50 } }))

describe('My adapter', adapterTests(testNames)(app, errors, 'test', 'id'))

Scenario - Filtering service results with select

Applies $select projection inside a custom service find method.

import { select } from './source/adapter-commons/src'
import { Params } from '@feathersjs/feathers'

class MyService {
  private data = [
    { id: 1, name: 'Alice', secret: 'hidden' },
    { id: 2, name: 'Bob', secret: 'hidden' }
  ]

  async find(params: Params) {
    // select honours params.query.$select automatically
    const filter = select(params, 'id') // 'id' always included
    return filter(this.data)
  }
}

// Client sends: GET /my-service?$select[]=id&$select[]=name
// Result: [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }]

File walkthrough

• adapter-commons/ - AdapterBase class, query normalisation (filterQuery), field selection helper (select), and sort utilities shared by all adapters.
• adapter-tests/ - adapterTests runner that composes basicTests, methodTests, and syntaxTests into a single Mocha-compatible suite.
• authentication/ - AuthenticationService, AuthenticationBase, JWTStrategy, and the authenticate/connection/event hooks for server-side auth.
• authentication-client/ - AuthenticationClient class, MemoryStorage/StorageWrapper, and client hooks (authentication, populateHeader) for browser and Node clients.
• authentication-local/ - LocalStrategy that validates plaintext or hashed passwords against a user service.
• authentication-oauth/ - OAuth2 strategy base class and provider-specific integrations.
• cli/ - The feathers CLI binary; delegates to generators/ for code generation commands.
• client/ - Pre-bundled isomorphic client combining rest-client and socketio-client.
• commons/ - Low-level utilities (_ object with pick, omit, etc.) and event-mixin logic used across all packages.
• configuration/ - Loads config/default.json (and environment overlays) via node-config; validates against a JSON schema.
• create-feathers/ - npm init feathers entry point; calls the CLI generators interactively.
• errors/ - FeathersError base and all standard subclasses (BadRequest, NotAuthenticated, NotFound, etc.).
• express/ - express() wrapper that adds Feathers service routing, error handling middleware, and REST transport.
• feathers/ - Core feathers() factory, Application class, hook execution engine, and service mixin.
• generators/ - Plop templates and actions for generating services, hooks, authentication, and adapters.
• knex/ - KnexAdapter providing full CRUD over any Knex-supported SQL database.
• koa/ - Koa middleware transport equivalent to the Express package.
• memory/ - MemoryService backed by an in-process Map; ideal for tests and prototyping.
• mongodb/ - MongoDBAdapter wrapping the native mongodb driver.
• rest-client/ - fetch and axios based REST transport for the Feathers client.
• schema/ - Resolver system (resolve, Resolver) and JSON-Schema-based validators used with services.
• socketio/ - Socket.io server transport that maps socket events to Feathers service calls.
• socketio-client/ - Socket.io client transport for use with the Feathers client.
• transport-commons/ - Routing, channel, and event-publishing logic shared by Express, Koa, and Socket.io transports.
• typebox/ - TypeBox schema helpers (Type, query schema builders) integrated with @feathersjs/schema.

Common pitfalls and fixes

• Circular path aliases: If tsconfig paths point into source/ while node_modules also has the published packages, TypeScript resolves both and emits duplicate-identifier errors. Fix: remove the published packages from node_modules or use npm link for each source package.
• JWT secret not set: AuthenticationService throws a cryptic error at startup when authentication.secret is missing from config. Fix: add "secret": "<32-char-random>" to config/default.json and never commit it.
• ESM/CJS interop: The source is compiled as ESM ("type": "module" in sub-package package.json). Mixing with CommonJS consumers requires "esModuleInterop": true and "module": "NodeNext" in your tsconfig. Fix: set both flags and use .js extensions in relative imports.
• Peer dependency version mismatch: jsonwebtoken v8 and v9 have incompatible type signatures. Fix: pin to jsonwebtoken@^9.0.0 and @types/jsonwebtoken@^9.0.0 together.
• adapterTests outside Mocha: The test runner calls describe/it globally; running it under Jest without a Mocha shim causes ReferenceError. Fix: use the jest-circus runner or install @jest/globals and patch globals before calling adapterTests.
• select returning empty objects: Forgetting to include the ID field in $select causes downstream lookups to fail. Fix: always pass idProp as an otherField argument: select(params, idProp).

Vibe-coding prompt template

I have a copy of the Feathers framework monorepo source in `./source/` and a
usage guide in `./USAGE.md`. The upstream package is `@feathersjs/feathers`.

Please help me integrate this source into my existing Node.js/TypeScript project
step by step:

1. Read `USAGE.md` fully before writing any code.
2. Add the `tsconfig.json` path aliases described in the "Project setup" section
   so my project resolves `@feathersjs/*` imports from `./source/` instead of
   from `node_modules`.
3. Create a `src/app.ts` that imports `feathers` from `./source/feathers/src`,
   registers an `AuthenticationService` from `./source/authentication/src` with
   a `JWTStrategy`, and registers a `MemoryService` from `./source/memory/src`
   protected by the `authenticate('jwt')` hook.
4. Show me how to run the `adapterTests` from `./source/adapter-tests/src`
   against the `MemoryService` using Mocha.
5. Use only exports that appear in `USAGE.md`'s "Public API" section. Do not
   invent any API surface.
6. Point out any peer dependencies I still need to install.

License and credit

The Feathers framework is released under the MIT License. See source/feathers/LICENSE (and individual package LICENSE files) for the full text. Upstream repository and package: @feathersjs/feathers by the Feathers contributors.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

Cloudflare REST API TypeScript SDK

Automation, Utilities & Developer Tools

Free