NaNoWriMo Promotes Manuscription
Wondering what’s next for npm?Check out our public roadmap! »


1.1.0 • Public • Published


dyconf can be used to generate a dynamically updated configuration from a template. It can also launch processes whenever a change is detected.

dyconf is a tool, not a library. It is best suited to run inside a docker container.

TL;DR you can find a working sample in consul-haproxy-dyconf.

How does this compare to consul-template or confd?

  • dyconf is not tied to a specific backend. You can use it with ZooKeeper, etcd, ... or your own REST services.
  • It uses node.js so you have access to npm modules.
  • dyconf uses lodash templates which, if you know JavaScript, might be easier to grok than the golang text templates that are used by confd and consul-template.

Install from npm

npm install dyconf -g


usage: dyconf -config=FILE [OPTIONS]

  -config   path to the template configuration
  -dump     dumps the generated template to the console
  -q        quiet, no logs

When you launch dyconf you need to specify -config=FILE, all other parameters are passed to the controller.


The Hjson configuration defines the following settings:

  • controller: path to the JavaScript controller (see below)
  • outputFile: configuration file to write to
  • refreshInterval: refresh interval in seconds unless handled by the controller
  • syslog: set to true to run a syslog server and print to the console (useful with the docker logs command)
  • logFile: path to a logfile to tail and print to the console (similar to syslog above)
  • startup: a shell script to run at startup
  • reload: a shell script to run whenever the configuration changes
  • shutdown: a shell script to run at when the process is terminated
  • template: inline template that will produce the output file

The controller can define additional settings.

dyconf uses lodash.template.


The controller is a JavaScript module that is executed by dyconf.

All controller functions are passed a context that contains:

  • args: CLI options (object)
  • argv: CLI arguments (array)
  • config: the template configuration
  • log: logging function
  • helpText: the standard help text (to append in init)

The module needs to export:


function init(ctx, showHelp)

init can be used to

  • evaluate commandline arguments,
  • create server connections (if any) or
  • show CLI help if showHelp is set.

Return true to continue, false to exit.


function fetchData(ctx)

Use fetchData to collect data required for the template.

Return a promise with the data that will be passed to the template.

start (optional)

function start(ctx, update)

Starts the update process. If start is not supplied a fixed interval (refreshInterval) will be used.

You can use start to watch for changes. Call update to trigger fetchData and to create/refresh the output file.


The Hello World source is available in the sample folder.


#hjson (go to for details)
  # define the controller that fetches the configuration and produces the content for outputFile
  controller: controller.js
  outputFile: /tmp/test.txt

  # refresh interval in seconds
  refreshInterval: 5

  # start a syslog server listening on port 514 (use rfc5424)
  # can be used to redirect logs for Docker
  syslog: false

  # logfile to tail to the console (can be "")
  # can be used like syslog for Docker
  logFile: ""

  # run on start/restart
    # prepare, configure files or run any required processes

    # here you would launch the main process (e.g. haproxy)
    # for the sample we only show the outputFile
    cat /tmp/test.txt

  # reload a new configuration
    # here you would tell the main process (e.g. haproxy)
    # to reload it's configuration
    # for the sample we only show the outputFile
    echo ---
    cat /tmp/test.txt

  # run on shutdown
    # here you would kill the main process

  # define the template to generate the outputFile
  `random` was generated by the code in controller.js
    <% [ "World", "Human" ].forEach(name => {
    %>Hello <%=name%>!
    <% }); %>
    In a real world scenario this file would contain the configuration generated by dyconf.

    Today's random value is <%=random%>!


// if you `require` any libraries you can add them to package.json &
// run `npm i` in the directory that contains this file.

var max;

// init runs at startup to configure options and initialize prerequisites

function init(ctx, showHelp) {
  var args=ctx.args;

  if (showHelp || ctx.argv.length>0) {
    console.error("usage: -max=#");
    console.error("  -max      max random sample value");
    return false;

  return true;

// fetchData can be used to query an external service (like consul)
// it needs to return a data structure that will be used to generate the template
function fetchData(ctx) {
  return new Promise((resolve, reject) => resolve(Math.random()*max))
    .then(x => ({ random: x }));

// start the update process (optional)
// can be used to implement a watch on a service
function start(ctx, update) {
  setInterval(update, 1000);

  init: init,
  fetchData: fetchData,
  start: start,


npm i dyconf

DownloadsWeekly Downloads






Last publish


  • avatar