Skip to main content
The application configuration is defined in the config/ directory and loaded using the @feathersjs/configuration package. Configuration files are loaded based on the NODE_ENV environment variable.

​
Configuration Files

Feathers applications use the following configuration structure:
  • config/default.json - Default configuration for all environments
  • config/production.json - Production-specific overrides
  • config/test.json - Test environment configuration
  • config/custom-environment-variables.json - Maps environment variables to configuration

​
Configuration Schema

When generating a new application with schemas enabled, Feathers creates a configuration schema that validates your application settings. 
import { Type, getValidator, defaultAppConfiguration } from '@feathersjs/typebox'
import type { Static } from '@feathersjs/typebox'
import { dataValidator } from './validators'

export const configurationSchema = Type.Intersect([
  defaultAppConfiguration,
  Type.Object({
    host: Type.String(),
    port: Type.Number(),
    public: Type.String()
  })
])

export type ApplicationConfiguration = Static<typeof configurationSchema>

export const configurationValidator = getValidator(configurationSchema, dataValidator)

​
Core Settings

​
host
string
required
The hostname the server should bind to.Default: localhostEnvironment Variable: HOSTNAME
​
port
number
required
The port number the server should listen on.Default: 3030Environment Variable: PORT
​
public
string
required
The path to the public directory for serving static files.Default: ./public/
​
origins
string[]
An array of allowed CORS origins. Used for cross-origin requests.Default: ['http://localhost:3030']

​
Pagination Settings

​
paginate
object
Default pagination settings for database queries.

​
Example Configuration

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

​
Usage

The configuration is automatically loaded and applied to your application:
src/app.ts
import configuration from '@feathersjs/configuration'

const app = express(feathers())

// Load configuration
app.configure(configuration())

// Access configuration values
const port = app.get('port')
const host = app.get('host')

​
Validation

When using schemas, configuration is validated during application setup. Invalid configuration will throw an error before the application starts:
src/app.ts
import configuration from '@feathersjs/configuration'
import { configurationValidator } from './configuration'

// Validate configuration on startup
app.configure(configuration(configurationValidator))

​
Environment Variables

Map environment variables to configuration values using config/custom-environment-variables.json: 
{
  "port": {
    "__name": "PORT",
    "__format": "number"
  },
  "host": "HOSTNAME",
  "authentication": {
    "secret": "FEATHERS_SECRET"
  }
}
The __format option converts the environment variable to the specified type. Supported formats include:
  • number - Parse as number
  • json - Parse as JSON
  • boolean - Parse as boolean

​
Best Practices

Keep environment-specific settings in separate files (production.json, staging.json, etc.) rather than in default.json.
Store sensitive values like API keys and secrets in environment variables, not in configuration files. Use custom-environment-variables.json to map them.
Always use configuration schemas to catch errors early and ensure your application has valid settings.
Add comments to your configuration schema to document what each setting does and its valid values.

Build docs developers (and LLMs) love

Get started for freeTalk to us