This package provides a solution for handling the configuration for NodeJs applications. The package supports both working as a standalone solution and online using config-server.
The configs are defined in the schemas package. It is used for validation, defining environment variable override, and for generating typescript types.
In order to use the package you need to install both the package itself, and the schemas package that handles all the config schemas.
npm install @map-colonies/schemas @map-colonies/config
Check the autogenerated documentation here.
import { config } from '@map-colonies/config';
import { commonBoilerplateV4 } from '@map-colonies/schemas';
const configInstance = await config({
configName: 'boiler-config',
configServerUrl: 'http://localhost:8080',
schema: commonBoilerplateV4,
version: 'latest',
offlineMode: false
});
const port = configInstance.get('server.port');
This section describes the API provided by the package for interacting with the configuration.
ConfigInstance<T>The ConfigInstance interface represents the your way to interact with the configuration. It provides methods to retrieve configuration values and parts.
T is the typescript type associated with the chosen schema. it can be imported from the @map-colonies/schemas package.
get<TPath extends string>(path: TPath): _.GetFieldType<T, TPath>path (TPath): The path to the desired value.getAll(): TgetConfigParts(): { localConfig: object; config: object; envConfig: object }localConfig, config, and envConfig parts of the configuration.
localConfig: The local configuration object.config: The remote configuration object.envConfig: The environment configuration object.getResolvedOptions(): BaseOptionsBaseOptions.initializeMetrics(registry: promClient.Registry): voidregistry (promClient.Registry): The prometheus registry to use for the metrics.This package allows you to configure various options for loading and managing configurations. Below are the available options and their descriptions.
schemaT extends SchemaWithTypefalseconfigNamestringtrueCONFIG_NAMEversion'latest' | numbertruelatest'latest' or a number.CONFIG_VERSIONconfigServerUrlstringtruehttp://localhost:8080CONFIG_SERVER_URLofflineModebooleantruefalseCONFIG_OFFLINE_MODEignoreServerIsOlderVersionErrorbooleantrueCONFIG_IGNORE_SERVER_IS_OLDER_VERSION_ERRORlocalConfigPathstringtrue./configThe following environment variables can be used to configure the options:
CONFIG_NAME: Sets the configName option.CONFIG_VERSION: Sets the version option.CONFIG_SERVER_URL: Sets the configServerUrl option.CONFIG_OFFLINE_MODE: Sets the offlineMode option.CONFIG_IGNORE_SERVER_IS_OLDER_VERSION_ERROR: Sets the ignoreServerIsOlderVersionError option.The package supports merging configurations from multiple sources (local, remote, and environment variables) and then validates the merged configuration against the schema.
localConfigPath option. The default path is ./config.configServerUrl option.version is set to 'latest', the latest version of the configuration is fetched. Otherwise, the specified version is fetched.Configuration options can be overridden by setting the corresponding environment variables as described in schema using the x-env-value key.
If an environment variable is set, it takes precedence over the value from the remote or local configuration.,
If the value of the x-env-format key is json, the environment variable value is parsed as JSON.
The configurations are merged in the following order of precedence:
If a configuration option is specified in multiple sources, the value from the source with higher precedence (as listed above) is used.
This section describes the possible errors that can occur when using the package, along with their codes and payload structures.
The package exposes a helper function called isConfigError to assert what is the error that was thrown and handle it as needed.
import { config, isConfigError } from '@map-colonies/config';
try {
const configInstance = await config({
configName: 'boiler-config',
configServerUrl: 'http://localhost:8080',
schema: commonBoilerplateV4,
version: 'latest',
offlineMode: false
});
} catch (error) {
if (isConfigError(error, 'configValidationError')) {
console.error('Config validation error:', error.payload);
}
}
optionValidationError1ValidationError[]configValidationError2ValidationError[]httpResponseError3{
headers: Record<string, string>;
statusCode: number;
body: string;
}
httpGeneralError4ErrorschemaNotFoundError5{
schemaPath: string;
}
schemasPackageVersionMismatchError6{
remotePackageVersion: string;
localPackageVersion: string;
}
schemaVersionMismatchError7{
remoteSchemaVersion: string;
localSchemaVersion: string;
}
promClientNotInstalledError8Errorprom-client package is not installed. The payload contains the error object.If for some reason you want to debug the package you can either use the getConfigParts or the getResolvedOptions functions described in the API or use the more powerful debug logger.
The package debug logger is implemented using the debug npm package and is configured using the DEBUG Environment variable.
The following are the values you can configure to use the debug option.
DEBUG=*Enables all the logs. Note that setting this option might enable debug logging of other packages.
DEBUG=@map-colonies/config*Enables all the logs available in this package.
DEBUG=@map-colonies/config:configEnables only the logs related to the main logic of the package.
DEBUG=@map-colonies/config:envEnables only the logs related to parsing environment variables from schemas, and retrieving them for use in the configuration.
DEBUG=@map-colonies/config:httpEnables only the logs related to http requests to the config-server.
DEBUG=@map-colonies/config:optionsEnables only the logs related to parsing and validation of the package initialization options.
DEBUG=@map-colonies/config:schemasEnables only the logs related to the retrieving of schemas.
DEBUG=@map-colonies/config:validatorEnables only the logs related to the validation of configurations.