Important: This is the documentation for a previous version of Feathers.
For the latest documentation please visit


npm version Changelog

$ npm install @feathersjs/configuration --save

@feathersjs/configuration is a wrapper for node-config which allows to configure a server side Feathers application.

By default this implementation will look in config/* for default.json which retains convention. As per the config docs you can organize "hierarchical configurations for your app deployments". See the usage section below for better information how to implement this.


The @feathersjs/configuration module is an app configuration function that takes a root directory (usually something like __dirname in your application) and the configuration folder (set to config by default):

const feathers = require('@feathersjs/feathers');
const configuration = require('@feathersjs/configuration');

// Use the application root and `config/` as the configuration folder
let app = feathers().configure(configuration())

Changing the location of the configuration directory

By default, Feathers will use the config/ directory in the root of your project’s source directory. To change this, e.g., if you have Feathers installed under the server/ directory and you want your configuration at server/config/, you have to set the NODE_CONFIG_DIR environment variable in app.js before importing @feathersjs/configuration:

e.g., In server/app.js:

process.env['NODE_CONFIG_DIR'] = path.join(__dirname, 'config/')
const configuration = require('@feathersjs/configuration')

The above code is portable, so you can keep your config/ directory with the rest of your Feathers files. It will work, for example, even if you change the directory from server/ to amazing-server, etc.

(The NODE_CONFIG_DIR environment variable isn’t used directly by @feathersjs/configuration but by the node-config module that it uses. For more information on configuring node-config settings, see the Configuration Files Wiki page.

Variable types

@feathersjs/configuration uses the following variable mechanisms:

  • Given a root and configuration path load a default.json in that path
  • Also try to load <NODE_ENV>.json in that path, and if found, extend the default configuration
  • Go through each configuration value and sets it on the application (via app.set(name, value)).
    • If the value is a valid environment variable (e.v. NODE_ENV), use its value instead
    • If the value starts with ./ or ../ turn it into an absolute path relative to the configuration file path
    • If the value is escaped (starting with a \) always use that value (e.g. \\NODE_ENV will become NODE_ENV)
  • Both default and <env> configurations can be modules which provide their computed settings with module.exports = {...} and a .js file suffix. See test/config/testing.js for an example.
    All rules listed above apply for .js modules.


In config/default.json we want to use the local development environment and default MongoDB connection string:

  "frontend": "../public",
  "host": "localhost",
  "port": 3030,
  "mongodb": "mongodb://localhost:27017/myapp",
  "templates": "../templates"

In config/production.json we are going to use environment variables (e.g. set by Heroku) and use public/dist to load the frontend production build:

  "frontend": "./public/dist",
  "host": "",
  "port": "PORT",
  "mongodb": "MONGOHQ_URL"

Now it can be used in our app.js like this:

const feathers = require('@feathersjs/feathers');
const configuration = require('@feathersjs/configuration');

const app = feathers()


If you now run

node app
// -> path/to/app/public
// -> localhost
// -> 3030
// -> mongodb://localhost:27017/myapp
// -> path/to/templates

Or via custom environment variables by setting them in config/custom-environment-variables.json:

  "port": "PORT",
  "mongodb": "MONGOHQ_URL"
$ PORT=8080 MONGOHQ_URL=mongodb://localhost:27017/production NODE_ENV=production node app
// -> path/to/app/public/dist
// ->
// -> 8080
// -> mongodb://localhost:27017/production
// -> path/to/templates

You can also override these variables with arguments. Read more about how with node-config

Is anything wrong, unclear, missing? Leave a comment or edit this page.

results matching ""

    No results matching ""