node package manager


environment-based, nested, addressable settings with modular pre-definable defaults


environment-based settings for javascript



For npm-based node.js projects, settns can be best installed by adding it to your project's package.json dependencies. First find the current version by running:

npm info settns version

then create or edit your existing package.json file (in your project's root) adding settns to its dependencies. Replace the "0.0.1" (leave the quotes) with the appropriate version.

  "name": "coolapp",
  "description": "my cool app",
  "version": "0.0.1",
  "private": true,
  "dependencies": {
      "settns": "0.0.1"

then running,

npm install


The git repository may be directly cloned into your project:

git clone

direct download


in a web browser

<script src="js/settns.js"></script>


var settns = require("settns");



A setting is an addressable value accessible through the settns function.

settns("ship.registry-number", "NCC-1701");

console.log(settns("ship.registry-number")); > "NCC-1701"


You may set defaults for any setting which settns automatically falls back to if no setting is found for the current environment.

settns.default("", "Enterprise");
settns.default("ship.registry-number", "NCC-1701");

settns("ship.registry-number", "NCC-1701-A");

console.log(settns("")); > "Enterprise"

console.log(settns("ship.registry-number")); > "NCC-1701-A"


Settings are stored in an environment. Settns has a current envrionment which values are read from.

settns.environment("search for spock");

console.log(settns.environment()); > "search for spock"

settns("ship.registry-number", "NCC-1701");

settns.environment("voyage home"); settns("ship.registry-number", "NCC-1701-A");

settns.environment("search for spock");

console.log(settns("ship.registry-number")); > "NCC-1701"

settns.environment("voyage home");

console.log(settns("ship.registry-number")); > "NCC-1701-A"

You may change a setting for a particular environment without changing the current environment:

settns("ship.registry-number", "NCC-1701-D", "next generation");

console.log(settns.environment()); > "voyage home"

console.log(settns("ship.registry-number")); > "NCC-1701-A"

settns.environment("next generation");

console.log(setns("ship.registry-number")); > "NCC-1701-D"


An example of how a contrived web server might use settns to provide seperation of different environments.

var settns = require("settns");

settns.default({ "server": { "port": 3000, "hostname": "example" } });

settns.environment("development", { "server.alias": ["localhost", ""] });

settns.environment("production", { "server": { "port": 80, "hostname": "", "alias": [""] } });

API Reference

settns(address[, value][, environment]);

Sets or retrieves a setting.

settns.environment([name][, settings]);

Sets or retrieves the current environment, or sets multiple settings for specified environment.

settns.default(settings|address[, value]);

Sets or retrieves a default value for a setting, or sets multple defaults at once.


Deletes all settings, causing all to revert to defaults.

settns.on(event, callback);

Binds a callback to an event.



Emitted when a setting's changes to a different value.


Emitted when a setting's value is updated, whether it is a new value or is unchanged.


Emitted when settings are reset to their defaults.

Running Tests

From the project root directory, run the unit tests with:

sbin/jasmine-node spec


View the LICENSE file.