Configuration

Environment-based configuration management for Feathers applications

The @feathersjs/configuration package provides a small but powerful configuration module for Feathers applications. It uses the node-config library to manage environment-specific configuration files.

Installation

npm install @feathersjs/configuration

Basic Usage

Configuration files should be placed in a config/ directory at the root of your application:

project/
├── config/
│   ├── default.json
│   ├── development.json
│   ├── production.json
│   └── test.json
├── src/
└── package.json

Initialize Configuration

import { feathers } from '@feathersjs/feathers'
import configuration from '@feathersjs/configuration'

const app = feathers()

app.configure(configuration())

// Access configuration values
const port = app.get('port')
const dbUrl = app.get('database').url

API

configuration

Initializes the configuration module and returns a function that can be used to configure a Feathers application.

import configuration from '@feathersjs/configuration'

const configFn = configuration()
app.configure(configFn)

schema · Schema<any> | Validator

Optional schema or validator function to validate configuration on setup

return · (app?: Application) => any

A function that configures the application with loaded configuration values

Configuration Files

default.json

The base configuration that applies to all environments:

{
  "host": "localhost",
  "port": 3030,
  "public": "./public/",
  "database": {
    "url": "mongodb://localhost:27017/myapp"
  }
}

Environment-Specific Files

Override defaults for specific environments:

production.json

{
  "host": "myapp.com",
  "port": 80,
  "database": {
    "url": "mongodb://prod-server:27017/myapp"
  }
}

development.json

{
  "database": {
    "url": "mongodb://localhost:27017/myapp-dev"
  }
}

Schema Validation

You can validate your configuration using a schema validator. This ensures your configuration is correct before the application starts.

import { feathers } from '@feathersjs/feathers'
import configuration from '@feathersjs/configuration'
import { Ajv, schema } from '@feathersjs/schema'

const configurationSchema = schema(
  {
    $id: 'ConfigurationSchema',
    type: 'object',
    required: ['port', 'host'],
    properties: {
      port: { type: 'number' },
      host: { type: 'string' },
      database: {
        type: 'object',
        required: ['url'],
        properties: {
          url: { type: 'string' }
        }
      }
    }
  } as const,
  new Ajv()
)

const app = feathers()

app.configure(configuration(configurationSchema))

await app.setup() // Will validate configuration and throw if invalid

Validation Errors

If validation fails, the setup hook will throw an error with detailed information:

try {
  await app.setup()
} catch (error) {
  console.error('Configuration validation failed:', error.data)
  // error.data contains array of validation errors
}

Using Without an App

You can also use the configuration module directly without a Feathers app:

import configuration from '@feathersjs/configuration'

const config = configuration()()

console.log(config.port) // 3030
console.log(config.database.url) // mongodb://localhost:27017/myapp

Environment Variables

The configuration module respects the NODE_ENV environment variable:

# Load development.json
NODE_ENV=development npm start

# Load production.json
NODE_ENV=production npm start

# Load test.json
NODE_ENV=test npm test

Custom Config Directory

You can specify a custom configuration directory using the NODE_CONFIG_DIR environment variable:

NODE_CONFIG_DIR=./my-config npm start

Configuration Merging

Configuration files are merged in the following order (later files override earlier ones):

1. default.json
2. {NODE_ENV}.json (e.g., production.json)
3. default-{instance}.json (for multi-instance deployments)
4. {NODE_ENV}-{instance}.json
5. local.json (not committed to source control)
6. local-{instance}.json

Advanced Features

Nested Configuration

Configuration values can be deeply nested:

{
  "authentication": {
    "secret": "my-secret",
    "strategies": ["jwt", "local"],
    "jwt": {
      "header": { "typ": "access" },
      "audience": "https://myapp.com",
      "issuer": "feathers",
      "algorithm": "HS256",
      "expiresIn": "1d"
    }
  }
}

Access nested values using dot notation:

const jwtConfig = app.get('authentication').jwt
const algorithm = app.get('authentication').jwt.algorithm

Null Values

The configuration module preserves null values:

{
  "optionalFeature": null
}

console.log(app.get('optionalFeature')) // null

Debug Logging

The configuration module uses the @feathersjs/commons debug utility. Enable debug logging to see configuration details:

DEBUG=@feathersjs/configuration npm start

This will output:

@feathersjs/configuration Initializing configuration for development environment
@feathersjs/configuration Setting port configuration value to 3030
@feathersjs/configuration Setting database configuration value to { url: '...' }

Type Safety

For TypeScript users, you can type your configuration:

interface AppConfiguration {
  host: string
  port: number
  database: {
    url: string
  }
  authentication: {
    secret: string
    jwt: {
      expiresIn: string
    }
  }
}

const port = app.get<number>('port')
const dbUrl = app.get<AppConfiguration['database']>('database').url