Page Contents


LoopBack applications have the following types of configuration files:

  • Application-wide configuration files, by default server/config.json. You can also use server/config.local.js to set values that you can’t with simple JSON.
  • Data source configuration files, by default server/datasources.json. You can also use server/datasources.local.js to set values that you can’t with simple JSON.
  • Application-level configuration of Models, by default server/model-config.json.
  • Middleware configuration files, by default server/middleware.json.
  • Configuration files for LoopBack components, by default server/component-config.json.

LoopBack will always load the following configuration files, if they exist:

  • server/config.json.
  • server/config.local.json or server/config.local.js
  • server/datasources.json
  • server/datasources.local.json or server/datasources.local.js
  • server/model-config.json
  • server/model-config.local.json or server/model-config.local.js
  • server/middleware.json
  • server/middleware.local.json or server/middleware.local.js
  • server/component-config.json
  • server/component-config.local.json or server/component-config.local.js

Additionally, when the NODE_ENV environment variable is set, LoopBack will load configuration from:

  • server/config.{_env_}.json/js
  • server/datasources.{_env_}.json/js
  • server/model-config.{_env_}.json/js
  • server/middleware.{_env_}.json/js
  • server/component-config.{_env_}.json/js

where {_env_} is the value of NODE_ENV (typically “development,” “staging,” or “production”). This enables you to set up configurations for specific environments (for example, development, staging, and production). 

Here are some examples of the application configuration files:

Here are some examples of data source configuration files:

Here are some examples of the middleware configuration files, the server/middleware{._env_}.json file:

For an example application, see

Application-wide configuration

Define application server-side settings in server/config.json.

You can override values that are set in config.json in:

  • config.local.js or config.local.json
  • config._env_.js or config._env_.json, where env is the value of NODE_ENV (typically development or production). For example config.production.json.

For example:


module.exports = {
  host: process.env.CUSTOM_HOST,
  port: process.env.CUSTOM_PORT

Turning off stack traces

By default, stack traces are returned in JSON responses. To turn disable stack traces in JSON responses:

  • Set the NODE_ENV environment variable to “production”
  • Include the following in server/middleware.production.json:


"final:after": {
    "loopback#errorHandler": {
      "params": {
        "includeStack": false

Disabling API Explorer

LoopBack API Explorer is great when you’re developing your application, but for security reasons you may not want to expose it in production.

For an application using loopback-component-explorer, to disable explorer in production:

  • Set the NODE_ENV environment variable to “production”.
  • Then in server/component-config.production.json:


  "loopback-component-explorer": null

Customizing REST error handling

You can customize the REST error handler by adding the error handler callback function to server/config.local.js as follows:


module.exports = {
  remoting: {
    errorHandler: {
      handler: function(err, req, res, next) {
        // custom error handling logic
        var log = require('debug')('server:rest:errorHandler'); // example
        log(req.method, req.originalUrl, res.statusCode, err);
        next(); // call next() to fall back to the default error handler

Exclude stack traces from HTTP responses

To exclude error stack traces from HTTP responses (typical in production), set the includeStack option of LoopBack errorHandler middleware to false in  middleware.json.

The standard configuration for development is:


"final:after": {
  "loopback#errorHandler": {}

For production, exclude stack traces from HTTP responses as follows:


"final:after": {
  "loopback#errorHandler": {
    "params": {
      "includeStack": false

Data source configuration

You can override values set in datasources.json in the following files:

  • datasources.local.js or datasources.local.json
  • datasources._env_.js or datasources._env_.json, where env is the value of NODE_ENV environment variable (typically development or production). For example, datasources.production.json.

Example data sources:


  // the key is the datasource name
  // the value is the config object to pass to
  // app.dataSource(name, config).
  db: {
    connector: 'memory'


  db: {
    connector: 'mongodb',
    database: 'myapp',
    user: 'myapp',
    password: 'secret'

Getting values from environment variables

You can easily set an environment variable when you run an application. The command you use depends on your operating system.

MacOS and Linux

Use this command to set an environment variable and run an application in one command:

$ MY_CUSTOM_VAR="some value" node .

or in separate commands:

$ export MY_CUSTOM_VAR="some value"
$ node .

Then this variable is available to your application as process.env.MY_CUSTOM_VAR.


On Windows systems, use these commands:

C:\> set MY_CUSTOM_VAR="some value"
C:\> node .