api.md

JavaScript API

In addition to using the simple CLI to scaffhold new projects quickly from the command line, you can also use the Khaos Javascript API for more advanced use cases.

If you have your own CLI, the Javascript API makes it super trivial to implement your own cli create method for scaffolding your own projects. Checkout the logo creation CLI for an example of this in action.

new Khaos(template)

var khaos = new Khaos('path/to/template');

Create a new Khaos instance, passing a path to the template directory (or file).

#generate(destination, [answers])

khaos.generate('path/to/destination', function(err){
  if (err) throw err;
  console.log('Generated!');
});

yield khaos.generate('path/to/destination');

A top-level convenience method that will read and write all in one go. If you omit answers, it will also parse and prompt before writing. Can be yielded.

#read()

khaos.read(function(err, files){
  if (err) throw err;
  ...
});

var files = yield khaos.read();

Read the template directory files from disk. Can be yielded.

#parse(files)

khaos.parse(files, function(err, schema){
  if (err) throw err;
  ...
});

var schema = yield khaos.parse(files);

Parse out a schema from a dictionary of template files. This is a Metalsmith files object. Can be yielded.

#prompt(schema)

khaos.prompt(schema, function(err, answers){
  if (err) throw err;
  ...
});

var answers = yield khaos.prompt(schema);

Prompt the user for answers to all of the keys in a schema. Can be yielded.

#write(destination, files, answers)

khaos.write('path/to/destination', files, answers, function(err){
  if (err) throw err;
  ...
});

yield write('path/to/destination', files, answers);

Template a dictionary of files with an answers dictionary, and write the results to a destination directory (or file). Can be yielded.

#use(plugin)

khaos.use(plugin);

function plugin(khaos) {
  khaos.schema({ name: { type: 'string' } });
}

Use a custom plugin function, which will be called with the khaos instance.

#before(plugin)

khaos.before(plugin);

function plugin(files, metalsmith) {
  for (var key in files) {
    var file = files[key];
    if (file.ignore) delete files[key];
  }
}

Add a plugin function to be run on the before hook. The before hook is run before any of the files are written to disk. This would be the hook to use if you want to manipulate the user's answers or the generated files before they are written to disk.

The plugin function is just a Metalsmith plugin that will be passed a files object and a metalsmith instance.

#after(plugin)

khaos.after(deploy);

Add a plugin function to be run on the after hook. The after hook is run after the files are written to disk. This would be the hook to use if you wanted to copy the files to another location, or perform build-process related tasks.

The plugin function is just a Metalsmith plugin that will be passed a files object and a metalsmith instance.

#format(options)

khaos.format({
  color: 'red',
  prefix: '  something  '
}); 

Pass in an options object to set the format for prompting. Options takes three properties: color, separator, and prefix. Since Khaos uses prompt-for, more information about the options can be found in the source.

{
  color: 'blue',
  separator: ': ',
  prefix:
}

#schema(schema)

khaos.schema({
  name: { type: 'string' },
  age: { type: 'number' },
  cheese: { type: 'boolean' }
});

Pass in a schema object. See the Schema docs for more information.

#order(array)

khaos.order(['age', 'name', 'cheese']);

Set the order to prompt for answers in by passing an array of schema keys.

#helpers(helpers)

khaos.helpers({
  'markdown': marked,
  'case': toCase
});

Pass in a dictionary of Handlebars helpers to template with.