Optional Readonly accesstrue
const config = new Conf({projectName: 'foo'});
config.set({
foo: {
bar: {
foobar: '🦄'
}
}
});
console.log(config.get('foo.bar.foobar'));
//=> '🦄'
Alternatively, you can set this option to false so the whole string would be treated as one key.
const config = new Conf({
projectName: 'foo',
accessPropertiesByDotNotation: false
});
config.set({
`foo.bar.foobar`: '🦄'
});
console.log(config.get('foo.bar.foobar'));
//=> '🦄'
Optional beforeThe given callback function will be called before each migration step.
This can be useful for logging purposes, preparing migration data, etc.
Optional clearThe config is cleared if reading the config file causes a SyntaxError. This is a good behavior for unimportant data, as the config file is not intended to be hand-edited, so it usually means the config is corrupt and there's nothing the user can do about it anyway. However, if you let the user edit the config file directly, mistakes might happen and it could be more useful to throw an error when the config is invalid instead of clearing.
false
Optional Readonly configThe mode that will be used for the config file.
You would usually not need this, but it could be useful if you want to restrict the permissions of the config file. Setting a permission such as 0o600 would result in a config file that can only be accessed by the user running the program.
Note that setting restrictive permissions can cause problems if different users need to read the file. A common problem is a user running your tool with and without sudo and then not being able to access the config the second time.
0o666
Optional configName of the config file (without extension).
Useful if you need multiple config files for your app or module. For example, different config files between two major versions.
'config'
Optional cwd?: stringYou most likely don't need this. Please don't use it unless you really have to.
The only use-case I can think of is having the config located in the app directory or on some external storage. Default: System default user config directory.
Optional defaults?: Readonly<T>Config used if there are no existing config.
Note: The values in defaults will overwrite the default key in the schema option.
Optional Readonly deserialize?: Deserialize<T>Function to deserialize the config object from a UTF-8 string when reading the config file.
You would usually not need this, but it could be useful if you want to use a format other than JSON.
JSON.parse
Optional encryptionNote that this is not intended for security purposes, since the encryption key would be easily found inside a plain-text Node.js app.
Its main use is for obscurity. If a user looks through the config directory and finds the config file, since it's just a JSON file, they may be tempted to modify it. By providing an encryption key, the file will be obfuscated, which should hopefully deter any users from doing so.
It also has the added bonus of ensuring the config file's integrity. If the file is changed in any way, the decryption will not work, in which case the store will just reset back to its default state.
When specified, the store will be encrypted using the aes-256-cbc encryption algorithm.
Optional fileExtension of the config file.
You would usually not need this, but could be useful if you want to interact with a file with a custom file extension that can be associated with your app. These might be simple save/export/preference files that are intended to be shareable or saved outside of the app.
'json'
Optional migrations?: Migrations<T>You can use migrations to perform operations to the store whenever a version is changed.
The migrations object should consist of a key-value pair of 'version': handler. The version can also be a semver range.
Note: The version the migrations use refers to the project version by default. If you want to change this behavior, specify the projectVersion option.
import Conf from 'conf';
const store = new Conf({
projectName: 'foo',
projectVersion: …,
migrations: {
'0.0.1': store => {
store.set('debugPhase', true);
},
'1.0.0': store => {
store.delete('debugPhase');
store.set('phase', '1.0.0');
},
'1.0.2': store => {
store.set('phase', '1.0.2');
},
'>=2.0.0': store => {
store.set('phase', '>=2.0.0');
}
}
});
Optional projectRequired unless you specify the cwd option.
You can fetch the name field from package.json.
Optional Readonly projectYou most likely don't need this. Please don't use it unless you really have to.
Suffix appended to projectName during config file creation to avoid name conflicts with native apps.
You can pass an empty string to remove the suffix.
For example, on macOS, the config file will be stored in the ~/Library/Preferences/foo-nodejs directory, where foo is the projectName.
'nodejs'
Optional projectRequired if you specify the migration option.
You can fetch the version field from package.json.
Optional schema?: Schema<T>JSON Schema to validate your config data.
Under the hood, the JSON Schema validator ajv is used to validate your config. We use JSON Schema draft-07 and support all validation keywords and formats.
You should define your schema as an object where each key is the name of your data's property and each value is a JSON schema used to validate that property. See more here.
import Conf from 'conf';
const schema = {
foo: {
type: 'number',
maximum: 100,
minimum: 1,
default: 50
},
bar: {
type: 'string',
format: 'url'
}
};
const config = new Conf({
projectName: 'foo',
schema
});
console.log(config.get('foo'));
//=> 50
config.set('foo', '1');
// [Error: Config schema violation: `foo` should be number]
Note: The default value will be overwritten by the defaults option if set.
Optional Readonly serialize?: Serialize<T>Function to serialize the config object to a UTF-8 string when writing the config file.
You would usually not need this, but it could be useful if you want to use a format other than JSON.
value => JSON.stringify(value, null, '\t')
Optional Readonly watch?: booleanWatch for any changes in the config file and call the callback for onDidChange or onDidAnyChange if set. This is useful if there are multiple processes changing the same config file.
false
Generated using TypeDoc
Access nested properties by dot notation.