Skip to content

Latest commit

 

History

History
95 lines (60 loc) · 5.23 KB

usermanual.md

File metadata and controls

95 lines (60 loc) · 5.23 KB
Raw

User manual

The purpose of this manual is to help you to use an application integrating confinode. In this manual, we consider that the application is using confinode with all default parameters. Please also refer to the application documentation in order to check possible specificities.

Configuration format

The name of the configuration file provided to the application can be:

  • an absolute path (e.g. D:\\config.json);
  • a path relative to current folder (e.g. ../config/config.yaml);
  • a module accessible from the current folder (e.g. tool-config);
  • a file of a module accessible from the current folder (e.g. tool-config/recommended.js).

Once the corresponding file found, the application will search for loader matching its extension. This loader may require that an additional module is accessible from the current folder.

The list of managed extensions with the required modules can be found in this file. You will see there that some extensions let you choose between multiple possible modules to use.

Once interpreted, your configuration file must return either an object literal or a string.

Configuration search

If you don't provide a configuration file name, the application will search a file from a list of standard names. For example, if your application is named starwars, its configuration will be searched, in this order:

  • in a starwars entry of the package.json file;
  • in the .starwarsrc file formatted as YAML or JSON;
  • in the .starwarsrc.* file with one of the managed extensions;
  • in the starwars.config.* file with one of the managed extensions;
  • in the .starwars/starwars.config.* file with one of the managed extensions.

Please note that if multiple files with same priority are accessible (with different extensions), application will arbitrarily select one and display a warning.

The configuration file is first searched in the current folder then, if not found, in the parent folder, and so on until the user home folder.

Indirection

It is possible to use indirections. If, for example, you put all your configuration files in a specific place, but you do not want to give this place each time you call the application, you can specify this place in one of the automatically searched files. For this, the file just has to return a string which will be used as true configuration file name.

Note that if you give a relative file name in your indirection, the file will be searched relative to the place of the current configuration file.

Examples

In the following example, configuration will be in the file /etc/starwars/config.yaml:

// package.json
{
  "starwars": "/etc/starwars/config.yaml"
}

In the following example, configuration will be in /home/user/config/starwars.json:

// /home/user/starwars/application/.starwarsrc.js
module.exports = '../../config/starwars.json'

Inheritance

It is possible to write a configuration file which inherit from one or more other files. This may be useful if, for example, you have a company global configuration to which you wish to add you specificities or, in the case of theme-oriented configuration files that you want to merge.

In order to do that, you have to add to your configuration object a key named extends which contains either directly the name of the file to inherit from or an array of file names to inherit from. If you inherit from multiple files, they are taken in the specified order, the data of the latter can replace the one of the former.

Note that if you give a relative file name in your extends entry, the file will be searched relative to the place of the current configuration file.

Example

In the following example, configuration will inherit in this order:

  • from the main file of package @stormtrooper/config;
  • from the file laser.js of package deathstar ;
  • from the file /home/user/starwars/rebel.json.

The configuration will also overwrite the entry apiKey whether it is in one of the inherited files or not.

# /home/user/starwars/application/.starwarsrc.yaml
extends:
  - '@stormtrooper/config'
  - 'deathstar/laser.js'
  - '../rebel.json'
apiKey: 'secret'

FAQ

Is it possible to create a module with my configuration?

It is of course possible to put a configuration file of any format in an external module. If this file is indicated as the main entry of the module (main key in package.json file), you will just have to give the module name to the application (using an indirection, for example). If not, you will have to indicate the file path inside the module, which allow to put many configurations for many applications inside the same module. For example, in order to load the starwars.yaml file which is inside the config folder of the corporate-cfg module, you will need to give: corporate-cfg/config/starwars.yaml.

Is it possible to inherit from an indirection?

It is possible to mix inheritances and indirections up to infinity… Or at least, as far as the computer resources allow it. The only limit is that it is not possible to create cycles (recursion).

However, be careful that if too many files have to be read, this could saturate the library cache and therefore impact performance.