FeathersJS Deployment & Usage Guide

Prerequisites

Node.js: Version 18.x LTS or higher (20.x recommended)
Package Manager: npm 9+, yarn 1.22+, or pnpm 8+
Git: For cloning repositories and version control
Database (choose one):
- MongoDB: 4.4+ (local or Atlas connection string)
- SQL Database: PostgreSQL 12+, MySQL 8.0+, SQLite 3, or MSSQL 2017+
TypeScript (optional but recommended): For type-safe development

Installation

Option A: New Application (Recommended)

Create a new Feathers application using the official generator:

npm create feathers my-new-app
# or
yarn create feathers my-new-app
# or
pnpm create feathers my-new-app

Navigate to the project and install dependencies:

cd my-new-app
npm install

Option B: Clone for Development/Contribution

Clone the monorepo and install dependencies:

git clone https://github.com/feathersjs/feathers.git
cd feathers
npm install

To run tests for a specific package:

cd packages/feathers  # or packages/mongodb, packages/knex, etc.
npm test

Configuration

Environment Variables

Create a .env file in the project root:

# Server Configuration
NODE_ENV=development
PORT=3030
HOST=localhost

# Database Configuration (choose based on your adapter)

# MongoDB
MONGODB_URI=mongodb://localhost:27017/myapp

# PostgreSQL/MySQL/SQLite (Knex)
DATABASE_URL=postgresql://user:password@localhost:5432/myapp
# or for SQLite
DATABASE_URL=./data.sqlite

# Authentication (if using @feathersjs/authentication)
JWT_SECRET=your-super-secret-jwt-key-change-in-production
JWT_EXPIRATION=1d

# Additional Service Config
LOG_LEVEL=info

Database Setup

MongoDB: Ensure your connection string is valid. The adapter automatically handles ObjectId conversion unless disableObjectify: true is set.

SQL (Knex): Configure connection in config/default.json or via environment variables:

{
  "database": {
    "client": "postgresql",
    "connection": "postgresql://user:password@localhost:5432/myapp",
    "migrations": {
      "directory": "./migrations"
    }
  }
}

Application Configuration

Edit config/default.json for service options:

{
  "host": "localhost",
  "port": 3030,
  "public": "./public/",
  "paginate": {
    "default": 10,
    "max": 50
  }
}

Build & Run

Development Mode

Start the development server with hot-reload:

npm run dev

The API will be available at http://localhost:3030 (or your configured PORT).

Production Build

Compile TypeScript to JavaScript:

npm run compile

Start the production server:

NODE_ENV=production npm start

Testing

Run all tests:

npm test

Run tests for a specific service or adapter:

cd packages/mongodb
npm test

Database Migrations (SQL only)

If using Knex with PostgreSQL, MySQL, or SQLite:

# Create a migration
npx knex migrate:make create_users_table

# Run migrations
npx knex migrate:latest

# Rollback
npx knex migrate:rollback

Deployment

Platform Recommendations

Railway/Render (Easiest)

Connect your Git repository
Set environment variables in the dashboard
Build command: npm run compile
Start command: npm start

Heroku

# Create app
heroku create my-feathers-app

# Set environment variables
heroku config:set NODE_ENV=production
heroku config:set DATABASE_URL=your-db-url

# Deploy
git push heroku main

Docker

Create a Dockerfile:

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run compile
EXPOSE 3030
CMD ["npm", "start"]

Build and run:

docker build -t my-feathers-app .
docker run -p 3030:3030 --env-file .env my-feathers-app

AWS/GCP/Azure

Build the application: npm run compile
Ensure NODE_ENV=production
Deploy the lib/ or dist/ directory (compiled output) along with package.json
Run npm ci --only=production on the server
Start with npm start or node lib/index.js

Production Checklist

Set NODE_ENV=production
Configure CORS origins in config/production.json
Use environment variables for secrets (JWT_SECRET, DB passwords)
Enable HTTPS/SSL termination (via reverse proxy or platform)
Configure logging (disable console logs, use structured logging)
Set up process manager (PM2, systemd, or platform-native)
Database: Use connection pooling for SQL databases
MongoDB: Ensure indexes are created for production queries

Troubleshooting

Port Already in Use

Error: EADDRINUSE: address already in use :::3030 Solution:

# Kill process on port 3030 (Linux/Mac)
lsof -ti:3030 | xargs kill -9
# Or change the port in .env
PORT=3031 npm run dev

MongoDB ObjectId Issues

Error: Cast to ObjectId failed or records not found Solution:

Ensure IDs are valid 24-character hex strings
Check if disableObjectify is set incorrectly in adapter options
Verify MongoDB connection string includes correct database name

Database Connection Failures (Knex)

Error: connect ECONNREFUSED 127.0.0.1:5432 Solution:

Verify database server is running
Check DATABASE_URL format: postgresql://user:pass@host:port/db
For SQLite, ensure the directory exists and is writable

TypeScript Compilation Errors

Error: Cannot find module or type errors Solution:

# Clean and rebuild
rm -rf lib/ node_modules
npm install
npm run compile

Authentication Issues

Error: NotAuthenticated: Invalid token Solution:

Verify JWT_SECRET is set and consistent across restarts
Check token expiration in configuration
Ensure Authorization header format: Bearer <token>

Real-time Events Not Working

Error: WebSocket connections failing Solution:

Verify @feathersjs/socket.io or @feathersjs/transport-commons is installed
Check if firewall/security groups allow WebSocket connections (port 3030 or 443)
For production behind a proxy (Nginx), ensure proxy_http_version 1.1 and proxy_set_header Upgrade $http_upgrade are set

Missing Service Methods

Error: MethodNotAllowed or service method undefined Solution:

Verify the service is registered in app.ts or app.js
Check if the method is listed in serviceOptions.methods
Ensure database adapter supports the operation (some methods may need explicit enablement)

How to Deploy & Use feathersjs/feathers