# App Config Files

The main way that users interact with App Config is .app-config.{ext} files. These are strongly tied to their corresponding schema file (.app-config.schema.{ext}).

Let's use a simple schema for reference:


type: object
additionalProperties: false

  - server
  - database

  server: { $ref: '#/definitions/Server' }
  database: { $ref: '#/definitions/Database' }

    type: object
    additionalProperties: false
    required: [port]
      port: { $ref: '#/definitions/IpPort' }
    type: object
    additionalProperties: false
    required: [host, port]
      host: { type: string }
      port: { $ref: '#/definitions/IpPort' }
      database: { type: string }
    type: integer
    minimum: 0
    maximum: 65535

Defining a schema is all well and good, but you're more concerned with the actual values.

Let's try just running app-config with the schema so far.

npx @app-config/cli vars

You should receive an error, something like this:

NotFoundError: FlexibleFileSource could not find file with .app-config.{yml|yaml|toml|json|json5}

App Config is trying to search for an .app-config.{ext} file. This is the default path that's searched.


port = 8888

host = "central-server"
port = 5432

We created a file called .app-config.toml. Our choice of TOML here is completely unimportant.

We'll try running again.

$ npx @app-config/cli vars

$ npx @app-config/cli create -f json5
  server: {
    port: 8888,
  database: {
    host: 'central-server',
    port: 5432,

We can check to make sure the schema will catch errors as well. Let's change the config values a bit:

port = 8888

host = true
port = 5432
$ npx @app-config/cli vars
# ... output omitted
[ValidationError: Config is invalid: config.database.host should be string]

# Environment Specific Files

App Config has two built-in ways to deal with environment specific values.

  1. Files can be named .app-config.{env}.{ext}, these take precedent and are not merged.
  2. Inside of .app-config.{ext} files, properties can use a special $env key.

The .app-config.production.yml file is entirely separated from development values. App Config will only load values from the file corresponding to the current environment. The same is true for .app-config.secrets.{env}.{ext} files as well.

Environments are defined by APP_CONFIG_ENV, NODE_ENV or ENV (in that order, whichever is defined). It's entirely valid for no environment to be defined. Errors will be thrown if no corresponding files / values can be found for the current environment. Note that .app-config.{ext} is the fallback, if the file exists.

Environments can be aliased as well. .app-config.dev.{ext} is equivalent to .app-config.development.{ext} for example. dev=development and prod=production are the only predefined aliases, but this can be customized.

A common pattern is to use merging, for the best of both worlds.


# this file has all "default" values

port = 8888

host = "central-server"
port = 5432


  // since we merge the default values in
  // we only need to override environment-specific values
  $extends: '.app-config.toml',
  server: {
    port: 80

Because of the deep merging algorithm, this tends to work fairly well.

# Environment Specific Values

If you have shared configuration between environments, you might prefer a second option.

      default: 3000
      production: 80

In any App Config file, this structure is flattened at load time.

$ NODE_ENV=production npx @app-config/cli v

$ NODE_ENV=qa npx @app-config/cli v

This functionality is implemented entirely as a parsing extension. It can be used in secret files as well.

# Environment Variables (APP_CONFIG)

Above all else, App Config will look for an environment variable called APP_CONFIG. This is basically the first check done. Day-to-day, you likely won't use this for development. But, for deployment of applications, this is generally the best way to use App Config.

The value of this variable should be a parseable string, containing the full config object. Strictly speaking, APP_CONFIG can be in any supported file format. From a standards perspective, we want this variable to be valid JSON - there are a lot less ambiguities and it's easier to support in other languages.

So what's the deal? Why deploy using a single variable like this?

Basically, it's extremely flexible to use environment variables as configuration. That's why tools like .env are popular - it's practically the only way to configure a docker container, for example. You can (and do try!) mount volumes with config files, and use app-config that way. But we feel that it's better to use APP_CONFIG.

docker run \
  -e APP_CONFIG=$(NODE_ENV=production npx @app-config/cli create -s --format json) \

This example is a bit contrived, but you probably get the idea here. It's typical to "serialize" configuration at deploy time. That way, there's not multiple files to read - just the one variable.

Along these lines, the App Config CLI provides APP_CONFIG when running nested commands. This is easy to demonstrate by "calling itself".

$ npx @app-config/cli -- ./node_modules/.bin/app-config c --verbose
[app-config][VERBOSE] Trying to read APP_CONFIG for configuration
[app-config][VERBOSE] EnvironmentSource guessed that APP_CONFIG is JSON FileType

Most hosting platforms provide some way to inject environment variables into running apps at deploy time. Running app-config create is an easy way to "spit out" the full configuration, suited for the deployment environment.

# Continuous Integration and Extension

Either APP_CONFIG_CI or APP_CONFIG_EXTEND can be set in an environment variable to change specific values. These variables are parsed just like APP_CONFIG (they can be JSON, YAML, etc). They are merged deeply and override any values that they define.

$ APP_CONFIG_EXTEND='{database:{host:"mock-server"}}' npx @app-config/cli v -s

This is, of course, most useful for CI. Your jobs could define value overrides for testing or deployment.

# Loading Strategy

When loading configuration, App Config performs the following:

  1. Is the APP_CONFIG environment variable defined?
    • If yes, guess it's file format (by trying to parse it) and use the parsed object
    • If defaultValues were passed into loadConfig, merge them
    • This is the full config. Files are not read
  2. Resolve the current environment, based on APP_CONFIG_ENV, NODE_ENV or ENV
    • Resolve environment aliases (dev -> development, prod -> production)
  3. Load main config file:
    1. Look for .app-config.{env}.{yml|yaml|toml|json|json5}, whichever is found first
    2. Look for .app-config.{yml|yaml|toml|json|json5}, whichever is found first
  4. Load secrets config file (this is allowed not to exist):
    1. Look for .app-config.secrets.{env}.{yml|yaml|toml|json|json5}, whichever is found first
    2. Look for .app-config.secrets.{yml|yaml|toml|json|json5}, whichever is found first
  5. Merge the main and secret config values as the full config
  6. If defaultValues were passed into loadConfig, merge them
  7. Look for APP_CONFIG_EXTEND or APP_CONFIG_CI environment variables
    • If defined, guess the format and parse it.
    • Merge this value on top of loaded configuration

# Merging Algorithm

Given a and b:

  • If either a or b is not an object (arrays not included), prefer b.
  • Iterate over keys of both, and merge each entry recursively using the same strategy.
    • Non-overlapping keys chose the existing entry.

# Customizing

We aim to make almost everything about config loading customizable. This should be true of the CLI and Node.js API.

See meta file options for a list of available customizations. The Node.js API has more possible options.

# Generating a .env file

Fairly easily, we could use App Config as a generator for .env files.

npx @app-config/cli vars -s > .env

This might be useful for applications you don't control, but want to use App Config for.