Runtime Configuration for Node.js

Concept & Usage

A runtime configuration reference and overview of all concepts and features.

How to Configure

How It Works

You can maintain your configuration in several ways. Here is a sample configuration using .cdsrc.json and package.json and the resulting effective configuration.

  1. Your .cdsrc.json
     "build": { "target": ".out" },
     "i18n": { "default_language": "de" } ,
     "deploy": { "no_save": true }
  2. Your package.json
     "cds": {
        "build": { "target": "genfolder" },
        "i18n": { "default_language": "de" } ,
        "deploy": { "no_save": true }

As package.json has precedence over cdsrc.json, for Node.js, the result is this effective configuration: --> "genfolder"
cds.env.i18n.default_language  -->  "de"
cds.env.deploy.no_save  -->  true

Environment Variables

Single properties can be set by using environment variables with prefix CDS_ as in CDS_BUILD_TARGET = "genfolder".

Structured configuration is passed by the special environment variable CDS_CONFIG. It contains a JSON string similar to the cds section in package.json (no cds node required in CDS_CONFIG). Environment variables for single properties have higher precedence than CDS_CONFIG.

The environment mock file default-env.json is supported. Entries in this file act like setting environment variables, in case the real variables haven’t been set.


Dependencies to databases and services can be configured by listing them within a requires section.

The subnodes below requires are static names, which can be referenced in coding as well (cds.env.requires.orderdata.credentials...).


"cds": {
   "requires": {
      "db": {    // a static name identifying this dependency.
        "kind": "hana",
        "model": "srv-hana",
        "credentials": {}   // can be explicitly configured here,
                            // but will be overruled by VCAP_SERVICES
                            // if a matching entry is found therein.
      "uaa": {
         "kind": "xsuaa",
         "credentials": { }
  • kind

    Contains one out of a list of reserved kinds of dependencies.

  • credentials

    Contains all information required to connect to and use this dependency. The credentials format depends on the kind of dependency. If a matching entry in the VCAP_SERVICES environment variable can be found, then credentials is filled from VCAP_SERVICES.

Not all dependencies can be found in VCAP_SERVICES (for example, "kind": "sqlite").


If VCAP_SERVICES is present, then credentials for dependencies must be taken from this variable. The existing subnodes of requires are matched against VCAP_SERVICES. There are multiple matching methods that are applied in order. If one match is found, the matching entry is taken over into the effective configuration. The remaining matching methods aren’t executed.

Explicit Configuration

You explicitly configure the subproperty using a configuration file, environment variable, or command line. This configuration affects the effective configuration before matching to VCAP_SERVICES. So, if has been configured, the match is based on the value for Using such a configuration, can disambiguate the “space sharing” scenario as well.

We’re using YAML notation for representing effective configurations:

Explicit match


Set using the environment variable: CDS_REQUIRES_DB_VCAP_NAME.

Simple Match

The name of the requires subnode is matched against name in VCAP_SERVICES. The match is successful if there’s exactly one match.

Simple match

The easiest option is to create a service instance with the same name as used in the requires section.

If you share one Cloud Foundry space with multiple developers, you can achieve separation by using multiple service instances with different names. In this case, they shall specify a binding_name when creating the service binding on Cloud Foundry. binding_name must then match the name of the requires section.

Simple match

Service Tags

When sharing a space, as an alternative to use a binding_name, you can set a tag to enable the match. For instance, using the command line:

cf create-service hana hdi-shared mydb -t "cds:db"

match by tags


If none of the above methods are applicable, then two heuristic methods are applied.

First, kind is compared to the content of the tag array in VCAP_SERVICES. If a match is found, search is completed and the matching credentials are returned.

If this method doesn’t lead to a match, kind is compared to the label property in VCAP_SERVICES.


This works, because label is supposed to reflect the “name of the service offering” and because we choose the list of kind in accordance with the SAP Cloud Platform Service Broker Catalog.


Profiles are a means to override default configuration values in configuration files. To override configuration comes in handy if you want to start the application with a deviating configuration.


In this sample .cdsrc.json, the requires section at the top is the default configuration to connect to SAP HANA. Then, for SQLite, a profile named development is introduced through the [...] notation. It overrides the default configuration if the development profile is active.

   "requires": {
      "db":  { "kind": "hana" }
   "[development]": {
      "requires": {
         "db": {
            "kind": "sqlite",
            "credentials": { "database": "my.db" }


Profiles are activated through the environment variable NODE_ENV. If NODE_ENV is not set, the profile development is activated, a convention adopted by many Node.js applications interpreting NODE_ENV. Usually, in continuous integration (CI) builds and Cloud Foundry deployments, NODE_ENV is set to production automatically.

Launch a Node.js server with the ad hoc activated production profile:

NODE_ENV=production  cds run
env NODE_ENV=production FOO=bar  cds run  # for multiple variables
SET NODE_ENV production
cds run
$env:NODE_ENV = "production"
cds run

Effective Configuration

Use cds env to list the effective configuration, which has all configuration files and profiles merged.

Single blocks or values can be read through cds env get. For example cds env get requires lists the requires block from the CDS configuration.

The effective configuration highly depends on the working directory and the current process or shell environment. Use cds env src to list all sources of configuration, that is, all files from which configuration is read.

Use cds help env to see all options.

Not all configuration keys are public APIs. When referring to a key, consult the documentation of the respective tool to find out.

Application Configuration

An application can add its own configuration properties, which are then made available in the effective environment following the same rules as for cds configuration.



"myapp": {
   "prop1": "value1",
   "prop2": "value2"

Environment variable MYAPP_PROP2 = “valueX”.

For Node.js, we provide an API to load the configuration node “myapp”:

let c = cds.env.for('myapp')  //> c = {prop1: 'value1', prop2: 'valueX'}