The 'conf' npm package is a simple yet powerful configuration management tool for Node.js applications. It allows you to easily store and retrieve configuration data, manage defaults, and handle schema validation. The data is stored in a JSON file, making it easy to read and modify.
Store and Retrieve Configuration Data
This feature allows you to store and retrieve configuration data easily. The data is stored in a JSON file, and you can set and get values using simple methods.
const Conf = require('conf');
const config = new Conf();
// Set a value
config.set('unicorn', '🦄');
// Get a value
console.log(config.get('unicorn'));
//=> '🦄'Manage Default Values
You can define default values for your configuration settings. If a key is not set, the default value will be returned.
const Conf = require('conf');
const config = new Conf({
defaults: {
foo: 'bar'
}
});
console.log(config.get('foo'));
//=> 'bar'Schema Validation
You can define a schema for your configuration to ensure that the data meets certain criteria. This helps in maintaining data integrity and consistency.
const Conf = require('conf');
const schema = {
type: 'object',
properties: {
foo: {
type: 'string'
},
bar: {
type: 'number',
minimum: 0
}
}
};
const config = new Conf({ schema });
config.set('foo', 'baz');
config.set('bar', 42);
console.log(config.get('foo'));
//=> 'baz'
console.log(config.get('bar'));
//=> 42Configstore is another package for managing configuration data in Node.js applications. It provides similar functionality to 'conf', such as storing and retrieving data, managing defaults, and handling schema validation. However, 'conf' offers a more modern API and better TypeScript support.
Node-persist is a simple, zero-dependency, key-value storage library for Node.js. It provides persistent storage for configuration data, similar to 'conf'. However, 'conf' offers more advanced features like schema validation and default values management.
Nconf is a hierarchical configuration manager for Node.js. It supports multiple configuration sources such as command-line arguments, environment variables, and JSON files. While 'nconf' is more flexible in terms of configuration sources, 'conf' is simpler and easier to use for most use cases.
Conf is a general purpose configuration platform for Nodejs. It can be used to create simple config files or even more advance user scripts.
The config scripts are plain old javascript with a definition layer on top of it.
Here is an example:
server
hostname = "127.0.0.1"
port = 80
location = "/articles"
root = "/var/www/sites/my_site/articles"
expires = "30d"
end
location = "/home"
redirect = "/"
end
end
The above example would result in the following JavaScript graph when parsed:
{
server: { hostname: "127.0.0.1"
, port: 80
, location: [
{ url: "/articles"
, root: "/var/www/sites/my_site/articles"
, exipres: "30d"
},
{ url: "/home"
, redirect: "/"
}
]
}
}
As mention above, the config scripts is Javascript, so it is possible to mix your DSL with Javascript. This is a powerful feature, which let you do stuff like this:
LOCATIONS = ["/articles", "/comments", "/users"]
server
hostname = "127.0.0.1"
port = 80
LOCATIONS.forEach(function(path) {
location = path
root = "/var/www/sites/my_site" + path
expires = "30d"
end
});
location = "/home"
redirect = "/"
end
end
The API is defined by two functions: createContext and createScript. The
createContext creates a markup that can be used with createScript.
Construct a new config context object. The config context is then used to run a config script.
The markup is a data graph, that is used to describe the config script
layout. A simple example:
var conf = require("conf");
conf.createContext({
host: { type: "string", value: "localhost" },
port: { type: "number", value: 8080}
});
The first key, host, represents a String property with default
value "localhost". The second key, port, represents a Number property
with default value 8080.
A valid config script for example context above would look look like:
host = "10.0.0.1"
port = 80
See the "Defining context markup" -section for complete documentation.
Construct a new config script object, from specified path. An optional
filename can be set
This function is synchronous and throws an exception on read errors.
Represents a Script.
All errors produced by "conf" is derived from the class RuntimeError. The RunTimeError class inherits the native Error class.
Returns a simplified message, without stack trace information, but with error message and line number.
The getSimpleMessage method is useful when you want to show user what's
wrong, without showing what happen "behind-the-scene".
There is 15 different types of fields, each with it's own set of properties.
Many of the types share's a set of properties. For example, required can
be used with any type. The common properties are:
required set to true to indicate that the field is required.list indicates that there can be multiply definitions of the field.strict indicates that the field value should be validated strictly.value sets a default value for the field.idxignore indicates that the field should be ignored in an index.param has different meaning in different types. See type documentation for implementation.index use field in a index.onenter callback when entering a section (see section documentation for more details).onexit callback when exiting a section (see section documentation for more details).Some of the types can be used with a "shortcut". Shortcuts is used to quickly define a property, without adding additionally markup. Here is an example of a shortcut in action:
conf.createContext({
host: String
});
The above example is mapped to:
conf.createContext({
host: { type: "string" }
});
It is also possible to map the type with it's name:
conf.createContext({
host: "string"
});
A required field can be defined by typing the type name with capitals:
conf.createContext({
host: "STRING"
});
Which maps to:
conf.createContext({
host: { type: "string", required: true }
});
It is also possible to define a list with shortcut. Just encapsulate with brackets as follows:
conf.createContext({
host: ["string"]
});
The different types of fields are: boolean, string, number, array,
object, regexp, expression, path, static, wildcard section,
struct, custom, bytesize and timeunit.
Represents a boolean value. Valid values in strict mode are
true or false. Undefined values is converted to true in non-strict
mode.
The native class Boolean works as a shortcut for the boolean field type.
Represents a String value. Values, which is not of native type string, are
converted to a string object via the toString method in non-strict mode.
The native class String works as a shortcut for the string field type.
Represents a Number value. Values, which is not of native type number, are
converted to numbers via the parseInt function in non-strict mode.
The native class Number works as a shortcut for the string field type.
Represents an Array value. Values, which is not of native type array, are encapsulated with bracets in non-strict mode.
The native class Array works as a shortcut for the string field type.
Represents an Object value. All values, except undefined and null, are
accepted.
The native class Object works as a shortcut for the string field type.
Represents a RegExp value. String values is converted into RegExp instances via it's constructor in non-strict mode.
The native class RegExp works as a shortcut for the string field type.
Represents a string value, that is validated against a RegExp expression.
The field property ´param` MUST contain an RegExp instance.
An expression example:
createContext({
method: { type: "expression", param: /^(get|set)$/ }
});
A more convenience may be to use expression types shortcut:
createContext({
method: { type: /^(get|set)$/ }
});
Or, the even more convenience shortcut:
createContext({
method: /^(get|set)$/
});
Represents a file-system path value, with relative-path support. Values,
which is not of native type String, are converted to a string object via
the toString method in non-strict mode.
Relative path's is mapped against scripts workdir variable.
Example (markup):
createContext({
data_file: { type: "path" }
});
Example (config):
data_file = "./data/data.json"
Result for example above:
{ data_file: "/parent_directory_of_config_file/data/data.json" }
This field is currently not supported on Windows.
Represents a static value. Static values cannot be set, they behave more
like traditional constants, except that they cannot be accessed in
the config file, just the result.
The field property value must be set for static fields.
Example:
createContext({
debug: { type: "static", value: true }
});
Which results in:
{ debug: true }
Wildcards can contain any kind of value.
Represents a section. Sections is used to divide fields into groups.
Section's has a set of special properties that can be set:
property sets a default field for the section.index creates an index for the section, with specified name. This is
useful when the order of section fields is needed.section is the shortcut for sections.See use-cases in examples below.
The section scope MUST be closed with the built-in keyword end (see
section "Built-in keywords" for more details) when defining it in a
config file.
The field property param MUST be set for static fields.
A quick example:
createContext({
database: { type: "section", param: {
port: Number,
host: String
}}
});
---
database
port = 8080
host = "127.0.0.1"
end
Which results in:
{ database: {
port: 8080,
host: "127.0.0.1"
}}
One more convenient way would be to use the section shortcut. Here is
an example that represents the markup above:
createContext({
database: { section: {
port: Number,
host: String
}}
});
There is no need for the param property when defining sections with the
shortcut.
Represents a struct. Struct is similar to section's but cannot only contain one child field. The struct is also laking some of the special properties that section supports.
The special property property is supported though.
Note: The end keyword is NOT supported in struct fields.
createContext({
static_server: { type: "struct", param: {
port: { type: "static", value: 8080},
host: { type: "static", value: "127.0.0.1"}
}}
});
Represents a custom value. Custom values are validated with provided function.
Example:
function customValue(field, value, runtime) {
if (value !== "value") {
throw new Error("Expected value");
}
return value;
}
createContext({
my_custom: { type: "custom", param: customValue };
});
Custom values also have a shortcut. Just put the validator as type:
createContext({
my_custom: { type: customValue };
});
Represents a byte size value. Byte size values is defined by a number or a string expression.
The string expression is defined with a number and a suffix. Supported suffixes are:
b represents a byte.kb represents a kilobyte (1024 bytes)mb represents a megabyte (1024 * 1024 bytes)gb represents a gigabyte (1024 * 1024 * 1024 bytes)Here is an example with a string expression.
createContext({
max_file_size: { type: "bytesize" };
});
---
max_file_size = "12mb"
Represents a time unit value. Time unit values is defined by a number or a string expression.
The string expression is defined with a number and a suffix. Supported suffixes are:
ms represents a millisecond.s represents a second (1000 milliseconds)m represents a minute (60 * 1000 milliseconds)h represents an hour (60 * 60 * 1000 milliseconds)d represents a day (24 * 60 * 60 * 1000 milliseconds)Here is an example with a string expression.
createContext({
backup_interval: { type: "timeunit" };
});
---
backup_interval = "1h"
The return value is always in milliseconds.
There is two built-in config file keywords, end and include. The
keyword end is called as a property while the include is called as
a function.
The keyword end is used to close a scope (section). The script-engine
is automatically closing scopes on end of execution, but it's good to
always call end anyway.
section
field = "field value"
end
The keyword include imports another config script and executes it in
current runtime. The path argument must be set and should point
to the script to include. Relative-paths are accepted.
include("./mime_types.conf")
It is also possible to use wildcard patterns to include one ore more files. Supported special characters are "*" and "?".
include("./sites/*.conf");
Note: The include keyword does not check if config is already included. This could result in a never-ending loop if a config includes it self.
BSD-License.
Copyright (c) Johan Dahlberg 2011
FAQs
Simple config handling for your app or module
We found that conf demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.
Security News
Research
Socket's threat research team has detected five malicious npm packages targeting Roblox developers, deploying malware to steal credentials and personal data.
Security News
vlt introduced its new package manager and a serverless registry this week, innovating in a space where npm has stagnated.