Skip to main content
Feathers uses the powerful config module for application configuration. The @feathersjs/configuration package seamlessly integrates configuration management into your Feathers application.

​
Installation

npm install @feathersjs/configuration --save

​
Basic Setup

Configuration is typically set up in your main application file: 
import { feathers } from '@feathersjs/feathers'
import configuration from '@feathersjs/configuration'

const app = feathers()

// Load configuration from config/ folder
app.configure(configuration())

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

​
Configuration Files

The configuration module loads settings from JSON files in a config/ directory at your project root. Files are loaded based on the NODE_ENV environment variable.
1
Create the config directory
2
mkdir config
3
Add default.json
4
Create config/default.json with your default settings:
5
{
  "host": "localhost",
  "port": 3030,
  "public": "./public/",
  "origins": ["http://localhost:3030"],
  "paginate": {
    "default": 10,
    "max": 50
  }
}
6
Add environment-specific files
7
Create environment-specific files that override defaults:
8
  • config/development.json - Development settings
  • config/production.json - Production settings
  • config/test.json - Test settings
    • 9
    // config/test.json
{
  "port": 8998
}
    10
    Add environment variables mapping
    11
    Create config/custom-environment-variables.json to map environment variables:
    12
    {
  "port": {
    "__name": "PORT",
    "__format": "number"
  },
  "host": "HOSTNAME",
  "authentication": {
    "secret": "FEATHERS_SECRET"
  }
}

    ​
    Schema Validation

    You can validate your configuration at application startup using a schema. This ensures your app fails fast with clear errors if configuration is invalid. 
    import { Type, getValidator, defaultAppConfiguration } 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)
    Then use the validator when configuring your app: 
    import configuration from '@feathersjs/configuration'
import { configurationValidator } from './configuration'

app.configure(configuration(configurationValidator))
    The validator runs as a setup hook and will throw detailed validation errors if configuration is invalid: 
    // Example validation error
await app.setup() // Throws error if config invalid
// Error: [
//   {
//     instancePath: '/port',
//     keyword: 'type',
//     message: 'must be number'
//   }
// ]

    ​
    Common Configuration Patterns

    ​
    Database Configuration

    {
  "mongodb": "mongodb://localhost:27017/myapp",
  "postgres": {
    "client": "pg",
    "connection": {
      "host": "localhost",
      "port": 5432,
      "database": "myapp",
      "user": "postgres",
      "password": "secret"
    }
  }
}

    ​
    CORS Configuration

    {
  "origins": [
    "http://localhost:3030",
    "https://myapp.com"
  ]
}

    ​
    Authentication Configuration

    {
  "authentication": {
    "secret": "your-secret-key",
    "entity": "user",
    "service": "users",
    "authStrategies": ["jwt", "local"],
    "jwtOptions": {
      "header": { "typ": "access" },
      "audience": "https://yourdomain.com",
      "issuer": "feathers",
      "algorithm": "HS256",
      "expiresIn": "1d"
    }
  }
}

    ​
    Pagination Configuration

    {
  "paginate": {
    "default": 10,
    "max": 50
  }
}

    ​
    Environment Variables

    Configuration values can be overridden using environment variables through the custom-environment-variables.json file.

    ​
    Variable Formats

    The __format key tells the config module how to parse the environment variable: 
    {
  "port": {
    "__name": "PORT",
    "__format": "number"
  },
  "enabled": {
    "__name": "FEATURE_ENABLED",
    "__format": "boolean"
  },
  "items": {
    "__name": "ITEMS_JSON",
    "__format": "json"
  }
}

    ​
    Usage

    # Set environment variables
export PORT=8080
export HOSTNAME=0.0.0.0
export FEATHERS_SECRET=my-production-secret

# Start your app
node src/index.js
    Environment variables always take precedence over configuration files, making them perfect for production deployments.

    ​
    Accessing Configuration

    Access configuration values anywhere in your application using app.get(): 
    // In your application code
const port = app.get('port')
const host = app.get('host')
const dbConnection = app.get('mongodb')

// In hooks
app.hooks({
  before: {
    all: [
      async (context) => {
        const maxItems = context.app.get('paginate').max
        // Use configuration value
      }
    ]
  }
})

// In services
class MyService {
  async setup(app, path) {
    this.itemsPerPage = app.get('paginate').default
  }
}

    ​
    Using Configuration Without App

    You can also use configuration outside of the Feathers application context: 
    import configuration from '@feathersjs/configuration'

const configFunction = configuration()
const config = configFunction()

console.log(config.port) // 3030

    ​
    Best Practices

    Never commit sensitive information like API keys, database passwords, or authentication secrets to version control. Use environment variables for production secrets.

    ​
    1. Use .gitignore

    # .gitignore
config/local.json
config/local-*.json
config/production.json
.env

    ​
    2. Document Required Variables

    Create a .env.example file: 
    # .env.example
PORT=3030
NODE_ENV=development
FEATHERS_SECRET=your-secret-here
DATABASE_URL=mongodb://localhost:27017/myapp

    ​
    3. Validate Early

    Always use schema validation to catch configuration errors before your app starts serving requests.

    ​
    4. Use Typed Configuration

    Define a TypeScript type for your configuration: 
    export type ApplicationConfiguration = {
  host: string
  port: number
  public: string
  origins: string[]
  paginate: {
    default: number
    max: number
  }
  mongodb?: string
  authentication?: {
    secret: string
    entity: string
    service: string
  }
}

// Use in your app declaration
type ServiceTypes = {
  // your services
}

const app: Application<ServiceTypes, ApplicationConfiguration> = express(feathers())

    ​
    5. Keep Defaults Sensible

    Your default.json should contain safe defaults for development. Production values should come from environment-specific files or environment variables.

    ​
    Debugging Configuration

    The configuration module uses the @feathersjs/commons debug module. Enable debug output: 
    DEBUG=@feathersjs/configuration npm start
    This will show:
    • Which environment is being loaded
    • What configuration values are being set
    • The final merged configuration

    ​
    Migration from Older Versions

    If you’re upgrading from Feathers v4 or earlier:
    1. Configuration setup remains largely the same
    2. Schema validation is new in v5 - add it for better reliability
    3. The configuration module now uses setup hooks for validation
    4. Type safety has been improved with TypeScript